index.ts

#!/usr/bin/env node

import {
  getConfig,
  ENABLE_DYNAMIC_API_URL,
  GITLAB_AUTH_COOKIE_PATH,
  GITLAB_CA_CERT_PATH,
  GITLAB_JOB_TOKEN,
  GITLAB_MCP_OAUTH,
  GITLAB_OAUTH_APP_ID,
  GITLAB_OAUTH_SCOPES,
  GITLAB_PERSONAL_ACCESS_TOKEN,
  GITLAB_POOL_MAX_SIZE,
  GITLAB_READ_ONLY_MODE,
  GITLAB_TOOLSETS_RAW,
  GITLAB_TOOLS_RAW,
  HOST,
  HTTP_PROXY,
  HTTPS_PROXY,
  IS_OLD,
  MCP_SERVER_URL,
  NODE_TLS_REJECT_UNAUTHORIZED,
  NO_PROXY,
  PORT,
  REMOTE_AUTHORIZATION,
  SESSION_TIMEOUT_SECONDS,
  SSE,
  STREAMABLE_HTTP,
  USE_GITLAB_WIKI,
  USE_MILESTONE,
  USE_OAUTH,
  USE_PIPELINE,
  GITLAB_TOOL_POLICY_APPROVE_RAW,
  GITLAB_TOOL_POLICY_HIDDEN_RAW,
} from "./config.js";

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { AsyncLocalStorage } from "node:async_hooks";
import express, { NextFunction, Request, Response } from "express";
import fetchCookie from "fetch-cookie";
import fs from "node:fs";
import os from "node:os";
import nodeFetch from "node-fetch";
import path, { dirname } from "node:path";
import { CookieJar, parse as parseCookie } from "tough-cookie";
import { fileURLToPath, URL } from "node:url";
import { z } from "zod";
import { initializeOAuthClient, GitLabOAuth } from "./oauth.js";
import { createGitLabOAuthProvider } from "./oauth-proxy.js";
import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
import { normalizeGitLabApiUrl } from "./utils/url.js";
import { estimateMergeCommitCount, filterDiffsByPatterns, summarizeWebhookEvents } from "./utils/helpers.js";
import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
import { GitLabClientPool } from "./gitlab-client-pool.js";
import {
  allTools,
  readOnlyTools,
  destructiveTools,
  parseEnabledToolsets,
  parseIndividualTools,
  buildFeatureFlagOverrides,
  isToolInEnabledToolset,
  TOOLSET_DEFINITIONS,
  ALL_TOOLSET_IDS,
  type ToolsetId,
} from "./tools/registry.js";
import {
  BulkPublishDraftNotesSchema,
  CancelPipelineJobSchema,
  CancelPipelineSchema,
  CreateBranchOptionsSchema,
  CreateBranchSchema,
  CreateDraftNoteSchema,
  CreateIssueLinkSchema,
  CreateIssueNoteSchema,
  CreateIssueOptionsSchema,
  CreateIssueSchema,
  CreateLabelSchema, // Added
  CreateMergeRequestNoteSchema,
  CreateMergeRequestDiscussionNoteSchema,
  CreateMergeRequestOptionsSchema,
  CreateMergeRequestSchema,
  CreateMergeRequestThreadSchema,
  CreateNoteSchema,
  CreateOrUpdateFileSchema,
  CreatePipelineSchema,
  CreateProjectMilestoneSchema,
  CreateRepositoryOptionsSchema,
  CreateRepositorySchema,
  CreateWikiPageSchema,
  CreateGroupWikiPageSchema,
  DeleteDraftNoteSchema,
  DeleteGroupWikiPageSchema,
  DeleteIssueLinkSchema,
  DeleteIssueSchema,
  DeleteLabelSchema,
  DeleteProjectMilestoneSchema,
  DeleteWikiPageSchema,
  DeleteMergeRequestNoteSchema,
  EditProjectMilestoneSchema,
  type FileOperation,
  ForkRepositorySchema,
  GetBranchDiffsSchema,
  GetCommitDiffSchema,
  GetCommitSchema,
  GetDraftNoteSchema,
  GetFileContentsSchema,
  GetIssueLinkSchema,
  GetIssueSchema,
  GetLabelSchema,
  GetMergeRequestDiffsSchema,
  GetMergeRequestSchema,
  GetMilestoneBurndownEventsSchema,
  GetMilestoneIssuesSchema,
  GetMilestoneMergeRequestsSchema,
  GetDeploymentSchema,
  GetEnvironmentSchema,
  GetNamespaceSchema,
  // pipeline job schemas
  GetPipelineJobOutputSchema,
  GetPipelineSchema,
  GetProjectMilestoneSchema,
  GetProjectSchema,
  type GetRepositoryTreeOptions,
  GetRepositoryTreeSchema,
  GetUsersSchema,
  GetWikiPageSchema,
  type GitLabCommit,
  GitLabCommitSchema,
  GitLabCompareResult,
  GitLabCompareResultSchema,
  type GitLabContent,
  GitLabContentSchema,
  type GitLabCreateUpdateFileResponse,
  GitLabCreateUpdateFileResponseSchema,
  GitLabDiffSchema,
  type GitLabDiscussion,
  // Discussion Types
  type GitLabDiscussionNote,
  // Discussion Schemas
  GitLabDiscussionNoteSchema, // Added
  GitLabDiscussionSchema,
  // Draft Notes Types
  type GitLabDraftNote,
  // Draft Notes Schemas
  GitLabDraftNoteSchema,
  type GitLabFork,
  GitLabForkSchema,
  type GitLabIssue,
  type GitLabIssueLink,
  GitLabIssueLinkSchema,
  GitLabIssueSchema,
  type GitLabIssueWithLinkDetails,
  GitLabIssueWithLinkDetailsSchema,
  type GitLabLabel,
  GitLabMarkdownUpload,
  GitLabMarkdownUploadSchema,
  type GitLabMergeRequest,
  type GitLabMergeRequestDiff,
  GitLabMergeRequestSchema,
  type GitLabMilestones,
  GitLabMilestonesSchema,
  GitLabNamespaceExistsResponseSchema,
  GitLabNamespaceSchema,
  type GitLabPipeline,
  type GitLabPipelineJob,
  type GitLabDeployment,
  type GitLabEnvironment,
  GitLabPipelineJobSchema,
  GitLabDeploymentSchema,
  GitLabEnvironmentSchema,
  GitLabPipelineSchema,
  type GitLabPipelineTriggerJob,
  GitLabPipelineTriggerJobSchema,
  type GitLabProject,
  type GitLabProjectMember,
  GitLabProjectMemberSchema,
  GitLabProjectSchema,
  type GitLabReference,
  GitLabReferenceSchema,
  type GitLabRepository,
  GitLabRepositorySchema,
  GitLabSearchBlobResultSchema,
  type GitLabSearchBlobResult,
  type GitLabSearchResponse,
  GitLabSearchResponseSchema,
  type GitLabTreeItem,
  GitLabTreeItemSchema,
  type GitLabUser,
  GitLabUserSchema,
  type GitLabUsersResponse,
  GitLabUsersResponseSchema,
  type GitLabWikiPage,
  GitLabWikiPageSchema,
  GroupIteration,
  type ListCommitsOptions,
  ListCommitsSchema,
  ListDraftNotesSchema,
  ListGroupIterationsSchema,
  ListGroupProjectsSchema,
  ListIssueDiscussionsSchema,
  ListIssueLinksSchema,
  ListIssuesSchema,
  ListLabelsSchema,
  ListMergeRequestDiffsSchema, // Added
  GetMergeRequestFileDiffSchema,
  ListMergeRequestChangedFilesSchema,
  ListMergeRequestDiscussionsSchema,
  ListMergeRequestsSchema,
  ListMergeRequestVersionsSchema,
  GetMergeRequestVersionSchema,
  GitLabMergeRequestVersionSchema,
  GitLabMergeRequestVersionDetailSchema,
  type GitLabMergeRequestVersion,
  type GitLabMergeRequestVersionDetail,
  ListNamespacesSchema,
  type ListPipelineJobsOptions,
  ListPipelineJobsSchema,
  type ListPipelinesOptions,
  ListPipelinesSchema,
  type ListDeploymentsOptions,
  ListDeploymentsSchema,
  type ListEnvironmentsOptions,
  ListEnvironmentsSchema,
  type ListPipelineTriggerJobsOptions,
  ListPipelineTriggerJobsSchema,
  type ListProjectMembersOptions,
  ListProjectMembersSchema,
  ListProjectMilestonesSchema,
  ListProjectsSchema,
  ListWikiPagesOptions,
  ListWikiPagesSchema,
  GetGroupWikiPageSchema,
  ListGroupWikiPagesSchema,
  UpdateGroupWikiPageSchema,
  type ListGroupWikiPagesOptions,
  MarkdownUploadSchema,
  DownloadAttachmentSchema,
  DownloadJobArtifactsSchema,
  GetJobArtifactFileSchema,
  type GitLabArtifactEntry,
  GitLabArtifactEntrySchema,
  ListJobArtifactsSchema,
  MergeMergeRequestSchema,
  ApproveMergeRequestSchema,
  UnapproveMergeRequestSchema,
  GetMergeRequestApprovalStateSchema,
  GetMergeRequestConflictsSchema,
  GitLabMergeRequestApprovalsResponseSchema,
  GitLabMergeRequestApprovalStateSchema,
  type GitLabApprovalUser,
  type GitLabMergeRequestApprovalState,
  type MergeRequestThreadPosition,
  type MyIssuesOptions,
  MyIssuesSchema,
  type PaginatedDiscussionsResponse,
  PaginatedDiscussionsResponseSchema,
  type PaginationOptions,
  PromoteProjectMilestoneSchema,
  PublishDraftNoteSchema,
  PlayPipelineJobSchema,
  PushFilesSchema,
  RetryPipelineJobSchema,
  RetryPipelineSchema,
  SearchCodeSchema,
  SearchGroupCodeSchema,
  SearchProjectCodeSchema,
  SearchRepositoriesSchema,
  UpdateDraftNoteSchema,
  UpdateIssueNoteSchema,
  UpdateIssueSchema,
  UpdateLabelSchema,
  UpdateMergeRequestNoteSchema,
  UpdateMergeRequestDiscussionNoteSchema,
  UpdateMergeRequestSchema,
  UpdateWikiPageSchema,
  VerifyNamespaceSchema,
  GitLabEventSchema,
  ListEventsSchema,
  GetProjectEventsSchema,
  GitLabEvent,
  ExecuteGraphQLSchema,
  type GitLabRelease,
  GitLabReleaseSchema,
  ListReleasesSchema,
  GetReleaseSchema,
  CreateReleaseSchema,
  UpdateReleaseSchema,
  DeleteReleaseSchema,
  CreateReleaseEvidenceSchema,
  DownloadReleaseAssetSchema,
  GetMergeRequestNotesSchema,
  GetMergeRequestNoteSchema,
  DeleteMergeRequestDiscussionNoteSchema,
  ResolveMergeRequestThreadSchema,
  GetWorkItemSchema,
  ListWorkItemsSchema,
  CreateWorkItemSchema,
  UpdateWorkItemSchema,
  ConvertWorkItemTypeSchema,
  ListWorkItemStatusesSchema,
  ListWorkItemNotesSchema,
  CreateWorkItemNoteSchema,
  MoveWorkItemSchema,
  ListCustomFieldDefinitionsSchema,
  GetTimelineEventsSchema,
  CreateTimelineEventSchema,
  ListWebhooksSchema,
  ListWebhookEventsSchema,
  GetWebhookEventSchema,
} from "./schemas.js";

import { randomUUID } from "node:crypto";
import { pino } from "pino";

const logger = pino({
  level: process.env.LOG_LEVEL || "info",
  transport: {
    target: "pino-pretty",
    options: {
      colorize: true,
      levelFirst: true,
      destination: 2,
    },
  },
});

/**
 * Available transport modes for MCP server
 */
enum TransportMode {
  STDIO = "stdio",
  SSE = "sse",
  STREAMABLE_HTTP = "streamable-http",
}

/**
 * Read version from package.json
 */
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const packageJsonPath = path.resolve(__dirname, "../package.json");
let SERVER_VERSION = "unknown";
try {
  if (fs.existsSync(packageJsonPath)) {
    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
    SERVER_VERSION = packageJson.version || SERVER_VERSION;
  }
} catch {
  // Intentionally ignored: version read failure is non-critical
}

/**
 * Create a new MCP Server instance with request handlers registered.
 * Each transport connection gets its own Server instance to prevent
 * cross-client data leakage (GHSA-345p-7cg4-v4c7).
 */
function createServer(): McpServer {
  // Precompute filtered tool list once at server creation (Steps 1–5 are static)
  // Step 1: Toolset filter — keep tools in enabled toolsets
  const toolsAfterToolsets = allTools.filter(tool =>
    isToolInEnabledToolset(tool.name, enabledToolsets)
  );

  // Step 2: Add GITLAB_TOOLS (individual tools bypass toolset filter)
  const toolsetToolNames = new Set(toolsAfterToolsets.map(t => t.name));
  const toolsAfterIndividual = [
    ...toolsAfterToolsets,
    ...allTools.filter(
      tool => individuallyEnabledTools.has(tool.name) && !toolsetToolNames.has(tool.name)
    ),
  ];

  // Step 3: Add legacy flag overrides (USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI)
  const afterIndividualNames = new Set(toolsAfterIndividual.map(t => t.name));
  const toolsAfterLegacy = [
    ...toolsAfterIndividual,
    ...allTools.filter(
      tool => featureFlagOverrides.has(tool.name) && !afterIndividualNames.has(tool.name)
    ),
  ];

  // Step 4: Read-only filter
  const toolsAfterReadOnly = GITLAB_READ_ONLY_MODE
    ? toolsAfterLegacy.filter(tool => readOnlyTools.has(tool.name))
    : toolsAfterLegacy;

  // Step 5: Regex denial filter
  let filteredTools = GITLAB_DENIED_TOOLS_REGEX
    ? toolsAfterReadOnly.filter(tool => !GITLAB_DENIED_TOOLS_REGEX!.test(tool.name))
    : [...toolsAfterReadOnly];

  // Step 5.5: Always include discover_tools meta-tool (bypasses toolset filter)
  const discoverTool = allTools.find(t => t.name === "discover_tools");
  const filteredToolNames = new Set(filteredTools.map(t => t.name));
  if (discoverTool && !filteredToolNames.has("discover_tools")) {
    // Respect read-only and regex denial filters
    const passesReadOnly = !GITLAB_READ_ONLY_MODE || readOnlyTools.has("discover_tools");
    const passesRegex = !GITLAB_DENIED_TOOLS_REGEX?.test("discover_tools");
    if (passesReadOnly && passesRegex) {
      filteredTools.push(discoverTool);
    }
  }

  // Step 5.7: Remove hidden policy tools
  if (hiddenToolSet.size > 0) {
    filteredTools = filteredTools.filter(tool => !hiddenToolSet.has(tool.name));
  }

  const mcpServer = new McpServer(
    {
      name: "better-gitlab-mcp-server",
      version: SERVER_VERSION,
    },
    {
      capabilities: {
        tools: {},
      },
    }
  );

  mcpServer.server.setRequestHandler(ListToolsRequestSchema, async () => {
    // Step 6: Gemini $schema cleanup + annotations (only dynamic step per request)
    // <<< START: Remove $schema for Gemini compatibility >>>
    const tools = filteredTools.map(tool => {
      const modified: any = { ...tool };

      // Safety net: remove $schema if present (toJSONSchema strips it for zod schemas,
      // but manually-defined schemas like discover_tools may still have it)
      if (modified.inputSchema && typeof modified.inputSchema === "object" && modified.inputSchema !== null) {
        if ("$schema" in modified.inputSchema) {
          modified.inputSchema = { ...modified.inputSchema };
          delete modified.inputSchema.$schema;
        }
      }

      // Add MCP tool annotations
      modified.annotations = {
        ...(readOnlyTools.has(tool.name) ? { readOnlyHint: true } : {}),
        ...(destructiveTools.has(tool.name) ? { destructiveHint: true } : {}),
        ...(approveToolSet.has(tool.name) ? { confirmationHint: true } : {}),
        openWorldHint: true,
      };

      // Inject _confirmed optional parameter for approve-policy tools
      if (approveToolSet.has(tool.name) && modified.inputSchema?.properties) {
        modified.inputSchema = {
          ...modified.inputSchema,
          properties: {
            ...modified.inputSchema.properties,
            _confirmed: {
              type: "boolean",
              description: "Set to true to confirm execution of this approval-required tool.",
            },
          },
        };
      }

      return modified;
    });
    // <<< END: Remove $schema for Gemini compatibility >>>

    return {
      tools, // return tool list with $schema removed
    };
  });

  mcpServer.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
    // Manually retrieve the session context using the session ID passed in the request.
    // This is a robust workaround for AsyncLocalStorage context loss.
    const sessionId = request.params.sessionId;
    const toolName = request.params.name;
    const start = Date.now();

    const logCompletion = (result: any) => {
      const durationMs = Date.now() - start;
      logger.info({ tool: toolName, event: "tool_call_done", durationMs }, `tool_call_done: ${toolName} (${durationMs}ms)`);
      return result;
    };

    const logError = (error: unknown) => {
      const durationMs = Date.now() - start;
      logger.error({ tool: toolName, event: "tool_call_error", durationMs, error: error instanceof Error ? error.message : String(error) }, `tool_call_error: ${toolName} (${durationMs}ms)`);
      throw error;
    };

    try {
      // Handle discover_tools meta-tool directly (needs access to mcpServer and filteredTools)
      if (toolName === "discover_tools") {
        const category = request.params.arguments?.category?.trim()?.toLowerCase();
        const currentToolNames = new Set(filteredTools.map(t => t.name));

        if (!category) {
          // List available categories with activation status
          const categories = TOOLSET_DEFINITIONS.map(def => ({
            id: def.id,
            toolCount: def.tools.size,
            active: [...def.tools].some(t => currentToolNames.has(t)),
            isDefault: def.isDefault,
          }));
          return logCompletion({
            content: [{
              type: "text",
              text: JSON.stringify({ categories, hint: "Call discover_tools with a category name to activate it" }, null, 2),
            }],
          });
        }

        if (!ALL_TOOLSET_IDS.has(category as ToolsetId)) {
          return logCompletion({
            content: [{
              type: "text",
              text: `Unknown category "${category}". Available: ${[...ALL_TOOLSET_IDS].join(", ")}`,
            }],
            isError: true,
          });
        }

        const toolsetDef = TOOLSET_DEFINITIONS.find(d => d.id === category);
        if (!toolsetDef) {
          return logCompletion({
            content: [{ type: "text", text: `Category "${category}" not found.` }],
            isError: true,
          });
        }

        // Check if already fully active
        const alreadyActive = [...toolsetDef.tools].every(t => currentToolNames.has(t));
        if (alreadyActive) {
          return logCompletion({
            content: [{
              type: "text",
              text: `Category "${category}" is already active (${toolsetDef.tools.size} tools).`,
            }],
          });
        }

        // Add tools from this toolset, respecting all filtering policies
        const newTools: typeof allTools = [];
        for (const tool of allTools) {
          if (!toolsetDef.tools.has(tool.name)) continue;
          if (currentToolNames.has(tool.name)) continue;
          if (GITLAB_READ_ONLY_MODE && !readOnlyTools.has(tool.name)) continue;
          if (GITLAB_DENIED_TOOLS_REGEX?.test(tool.name)) continue;
          if (hiddenToolSet.has(tool.name)) continue;
          newTools.push(tool);
        }

        if (newTools.length === 0) {
          return logCompletion({
            content: [{
              type: "text",
              text: `Category "${category}" has no additional tools to activate (all already active or filtered).`,
            }],
          });
        }

        filteredTools.push(...newTools);

        // Notify client that tool list has changed
        try {
          await mcpServer.server.sendToolListChanged();
        } catch {
          // Client may not support notifications - safe to ignore
        }

        const addedNames = newTools.map(t => t.name);
        logger.info({ event: "toolset_activated", category, toolCount: addedNames.length }, `Activated toolset: ${category} (+${addedNames.length} tools)`);

        return logCompletion({
          content: [{
            type: "text",
            text: JSON.stringify({
              activated: category,
              addedTools: addedNames,
              totalTools: filteredTools.length,
            }, null, 2),
          }],
        });
      }

      // Check approve policy: tool is exposed but requires explicit confirmation
      if (approveToolSet.has(toolName)) {
        const confirmed = request.params.arguments?._confirmed === true;
        if (!confirmed) {
          logger.info({ tool: toolName, event: "tool_call_approval_required" }, `Approval required: ${toolName}`);
          return logCompletion({
            content: [{
              type: "text",
              text: `Tool "${toolName}" requires confirmation. This tool is marked as requiring approval before execution. Re-call with _confirmed: true to proceed.`,
            }],
          });
        }
        // Strip _confirmed from args before forwarding to handler
        const { _confirmed, ...cleanArgs } = request.params.arguments || {};
        request.params.arguments = cleanArgs;
      }

      if ((REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId && authBySession[sessionId]) {
        const authData = authBySession[sessionId];
        const sessionContext: SessionAuth = {
          sessionId,
          header: authData.header,
          token: authData.token,
          lastUsed: authData.lastUsed,
          apiUrl: authData.apiUrl,
        };
        // Run the handler within the retrieved context
        const result = await sessionAuthStore.run(sessionContext, () => handleToolCall(request.params));
        return logCompletion(result);
      }
      // Fallback for non-remote-auth mode or if session is not found
      const result = await handleToolCall(request.params);
      return logCompletion(result);
    } catch (error) {
      logError(error);
    }
  });

  return mcpServer;
}

/**
 * Validate configuration at startup
 */
function validateConfiguration(): void {
  const errors: string[] = [];

  // Validate SESSION_TIMEOUT_SECONDS
  const timeoutStr = process.env.SESSION_TIMEOUT_SECONDS;
  if (timeoutStr) {
    const timeout = Number.parseInt(timeoutStr, 10);
    // Allow values >=1 for testing purposes, but recommend 60-86400 for production
    if (Number.isNaN(timeout) || timeout < 1 || timeout > 86400) {
      errors.push(
        `SESSION_TIMEOUT_SECONDS must be between 1 and 86400 seconds, got: ${timeoutStr}`
      );
    }
    if (timeout < 60) {
      logger.warn(
        `SESSION_TIMEOUT_SECONDS=${timeout} is below recommended minimum of 60 seconds. Only use low values for testing.`
      );
    }
  }

  // Validate MAX_SESSIONS
  const maxSessionsStr = process.env.MAX_SESSIONS;
  if (maxSessionsStr) {
    const maxSessions = Number.parseInt(maxSessionsStr, 10);
    if (Number.isNaN(maxSessions) || maxSessions < 1 || maxSessions > 10000) {
      errors.push(`MAX_SESSIONS must be between 1 and 10000, got: ${maxSessionsStr}`);
    }
  }

  // Validate MAX_REQUESTS_PER_MINUTE
  const maxReqStr = process.env.MAX_REQUESTS_PER_MINUTE;
  if (maxReqStr) {
    const maxReq = Number.parseInt(maxReqStr, 10);
    if (Number.isNaN(maxReq) || maxReq < 1 || maxReq > 1000) {
      errors.push(`MAX_REQUESTS_PER_MINUTE must be between 1 and 1000, got: ${maxReqStr}`);
    }
  }

  // Validate PORT
  const portStr = getConfig("port", "PORT");
  if (portStr) {
    const port = Number.parseInt(portStr, 10);
    if (Number.isNaN(port) || port < 1 || port > 65535) {
      errors.push(`PORT must be between 1 and 65535, got: ${portStr}`);
    }
  }

  // Validate GITLAB_API_URL format
  const apiUrls = getConfig("api-url", "GITLAB_API_URL")?.split(",") || [];
  if (apiUrls.length > 0) {
    for (const url of apiUrls) {
      try {
        new URL(url.trim());
      } catch {
        errors.push(`GITLAB_API_URL contains an invalid URL: ${url.trim()}`);
      }
    }
  }

  // Validate auth configuration
  const remoteAuth = getConfig("remote-auth", "REMOTE_AUTHORIZATION") === "true";
  const useOAuth = getConfig("use-oauth", "GITLAB_USE_OAUTH") === "true";
  const hasToken = !!getConfig("token", "GITLAB_PERSONAL_ACCESS_TOKEN");
  const hasJobToken = !!getConfig("job-token", "GITLAB_JOB_TOKEN");
  const hasCookie = !!getConfig("cookie-path", "GITLAB_AUTH_COOKIE_PATH");
  const mcpOAuth = getConfig("mcp-oauth", "GITLAB_MCP_OAUTH") === "true";
  const mcpServerUrl = getConfig("mcp-server-url", "MCP_SERVER_URL");

  if (!remoteAuth && !useOAuth && !hasToken && !hasJobToken && !hasCookie && !mcpOAuth) {
    errors.push(
      "Either --token, --job-token, --cookie-path, --use-oauth=true, --remote-auth=true, or --mcp-oauth=true must be set (or use environment variables)"
    );
  }

  if (mcpOAuth) {
    if (!mcpServerUrl) {
      errors.push(
        "MCP_SERVER_URL is required when GITLAB_MCP_OAUTH=true (e.g. https://mcp.example.com)"
      );
    } else {
      try {
        const u = new URL(mcpServerUrl);
        const isInsecure = u.protocol !== "https:";
        const isLocalhost = u.hostname === "localhost" || u.hostname === "127.0.0.1";
        const allowInsecure =
          process.env.MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL === "true";
        if (isInsecure && !isLocalhost && !allowInsecure) {
          errors.push(
            "MCP_SERVER_URL must use HTTPS in production " +
              "(set MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true for local dev)"
          );
        }
      } catch {
        errors.push(`MCP_SERVER_URL is not a valid URL: ${mcpServerUrl}`);
      }
    }

    if (!getConfig("api-url", "GITLAB_API_URL")) {
      errors.push("GITLAB_API_URL is required when GITLAB_MCP_OAUTH=true");
    }

    if (!getConfig("oauth-app-id", "GITLAB_OAUTH_APP_ID")) {
      errors.push(
        "GITLAB_OAUTH_APP_ID is required when GITLAB_MCP_OAUTH=true " +
          "(create an OAuth application in GitLab Admin with the required scopes)"
      );
    }
  }

  const enableDynamicApiUrl =
    getConfig("enable-dynamic-api-url", "ENABLE_DYNAMIC_API_URL") === "true";
  if (enableDynamicApiUrl && !remoteAuth) {
    errors.push("ENABLE_DYNAMIC_API_URL=true requires REMOTE_AUTHORIZATION=true");
  }

  if (errors.length > 0) {
    logger.error("Configuration validation failed:");
    errors.forEach(err => logger.error(`  - ${err}`));
    process.exit(1);
  }

  logger.info("Configuration validation passed");
}

let OAUTH_ACCESS_TOKEN: string | null = null;
let oauthClient: GitLabOAuth | null = null;
/**
 * Ensure the OAuth token is valid before making an API call.
 * Refreshes the token lazily (only when a tool is actually called).
 * This avoids background timers that cause issues with multiple instances.
 */
async function ensureValidOAuthToken(): Promise<void> {
  if (!oauthClient) return;

  if (oauthClient.hasValidToken()) return;

  try {
    logger.info("OAuth token expired or missing, refreshing...");
    const freshToken = await oauthClient.getAccessToken();
    OAUTH_ACCESS_TOKEN = freshToken;
    logger.info("OAuth token refreshed successfully");
  } catch (error) {
    logger.error("Failed to refresh OAuth token:", error);
    throw error;
  }
}

const GITLAB_DENIED_TOOLS_REGEX = (() => {
  const pattern = getConfig("denied-tools-regex", "GITLAB_DENIED_TOOLS_REGEX");
  if (!pattern) return undefined;

  // Reject patterns that are too long (potential ReDoS vector)
  const MAX_PATTERN_LENGTH = 200;
  if (pattern.length > MAX_PATTERN_LENGTH) {
    logger.error(
      `GITLAB_DENIED_TOOLS_REGEX pattern exceeds ${MAX_PATTERN_LENGTH} chars. Ignoring.`
    );
    return undefined;
  }

  // Reject patterns with nested quantifiers that can cause catastrophic backtracking (ReDoS)
  // e.g., (a+)+, (a*)+, (a+)*, (a{1,})+
  // Note: lookahead (?!), (?=), lookbehind (?<), and named groups (?<name>) are safe and allowed
  const NESTED_QUANTIFIER_PATTERN = /(\(.*[+*?].*\)|\[.*\])[+*?]/;
  if (NESTED_QUANTIFIER_PATTERN.test(pattern)) {
    logger.error(
      `GITLAB_DENIED_TOOLS_REGEX contains potentially unsafe nested quantifiers. Ignoring.`
    );
    return undefined;
  }

  try {
    const regex = new RegExp(pattern);
    // Dry-run against a sample string to catch immediate issues
    regex.test("sample_tool_name");
    return regex;
  } catch {
    logger.error(`Invalid GITLAB_DENIED_TOOLS_REGEX pattern: "${pattern}". Ignoring.`);
    return undefined;
  }
})();

// ---------------------------------------------------------------------------
// Tool policy: approve / hidden sets
// ---------------------------------------------------------------------------
const approveToolSet = new Set(
  (GITLAB_TOOL_POLICY_APPROVE_RAW || "")
    .split(",")
    .map(s => s.trim())
    .filter(Boolean)
);
const hiddenToolSet = new Set(
  (GITLAB_TOOL_POLICY_HIDDEN_RAW || "")
    .split(",")
    .map(s => s.trim())
    .filter(Boolean)
);

// Validate approve/hidden tool names against known tools at startup
{
  const knownToolNames = new Set(allTools.map(t => t.name));
  for (const name of approveToolSet) {
    if (!knownToolNames.has(name)) {
      logger.warn({ event: "unknown_approve_tool", name }, `GITLAB_TOOL_POLICY_APPROVE contains unknown tool: "${name}"`);
    }
  }
  for (const name of hiddenToolSet) {
    if (!knownToolNames.has(name)) {
      logger.warn({ event: "unknown_hidden_tool", name }, `GITLAB_TOOL_POLICY_HIDDEN contains unknown tool: "${name}"`);
    }
  }
}

const clientPool = new GitLabClientPool({
  apiUrls: (getConfig("api-url", "GITLAB_API_URL") || "https://gitlab.com")
    .split(",")
    .map(normalizeGitLabApiUrl),
  httpProxy: HTTP_PROXY,
  httpsProxy: HTTPS_PROXY,
  noProxy: NO_PROXY,
  rejectUnauthorized: NODE_TLS_REJECT_UNAUTHORIZED !== "0",
  caCertPath: GITLAB_CA_CERT_PATH,
  poolMaxSize: GITLAB_POOL_MAX_SIZE,
});

// Create cookie jar with clean Netscape file parsing
// Resolve cookie path once using os.homedir() for cross-platform support
const resolvedCookiePath = GITLAB_AUTH_COOKIE_PATH
  ? GITLAB_AUTH_COOKIE_PATH.startsWith("~/")
    ? path.join(os.homedir(), GITLAB_AUTH_COOKIE_PATH.slice(2))
    : GITLAB_AUTH_COOKIE_PATH
  : null;

const createCookieJar = async (): Promise<CookieJar | null> => {
  if (!resolvedCookiePath) return null;

  let cookieContent: string;
  try {
    cookieContent = await fs.promises.readFile(resolvedCookiePath, "utf8");
  } catch (error) {
    logger.error({ error, path: resolvedCookiePath }, "Failed to read cookie file");
    return null;
  }

  const jar = new CookieJar();
  for (let line of cookieContent.split("\n")) {
    // Handle #HttpOnly_ prefix
    if (line.startsWith("#HttpOnly_")) {
      line = line.slice(10);
    }
    // Skip comments and empty lines
    if (line.startsWith("#") || !line.trim()) {
      continue;
    }

    // Parse Netscape format: domain, flag, path, secure, expires, name, value
    const parts = line.split("\t");
    if (parts.length >= 7) {
      const [domain, , cookiePath, secure, expires, name, value] = parts;

      // Build cookie string in standard format
      const secureFlag = secure === "TRUE" ? "; Secure" : "";
      const expiresFlag =
        expires === "0"
          ? ""
          : `; Expires=${new Date(Number.parseInt(expires, 10) * 1000).toUTCString()}`;
      const cookieStr = `${name}=${value}; Domain=${domain}; Path=${cookiePath}${secureFlag}${expiresFlag}`;

      // Use tough-cookie's parse function for robust parsing
      const cookie = parseCookie(cookieStr);
      if (cookie) {
        const url = `${secure === "TRUE" ? "https" : "http"}://${domain.startsWith(".") ? domain.slice(1) : domain}`;
        jar.setCookieSync(cookie, url);
      }
    }
  }

  return jar;
};

// Auth retry helpers — extracted to auth-retry.ts for testability (no side effects)
export {
  headersToPlainObject,
  isNonReplayableBody,
  wrapWithAuthRetry,
  type AuthRetryConfig,
} from "./auth-retry.js";
import { wrapWithAuthRetry } from "./auth-retry.js";

/** Build AuthRetryConfig from module globals (lazy — reads globals at call time). */
function defaultAuthRetryConfig() {
  return {
    isOAuthEnabled: () => USE_OAUTH && oauthClient != null,
    refreshToken: (force: boolean) => oauthClient!.getAccessToken(force),
    onTokenRefreshed: (token: string) => { OAUTH_ACCESS_TOKEN = token; },
    buildAuthHeaders,
    logger,
  };
}

// Cookie jar and fetch - reloaded when cookie file changes
let cookieJar: CookieJar | null = null;
let fetch: typeof nodeFetch = wrapWithAuthRetry(nodeFetch, defaultAuthRetryConfig());
let lastCookieMtime = 0;
let cookieReloadLock: Promise<void> | null = null; // Mutex to prevent parallel reloads
// Auth proxies may redirect and set cookies on the first request. We make a throwaway
// request so subsequent requests have the correct cookies. Reset when cookies reload.
let initialSessionRequestMade = false;

// Cookie jar is loaded on first request via reloadCookiesIfChanged (lastCookieMtime=0 triggers load)

async function reloadCookiesIfChanged(): Promise<void> {
  if (!resolvedCookiePath) return;
  if (cookieReloadLock) return cookieReloadLock;

  cookieReloadLock = (async () => {
    try {
      const mtime = (await fs.promises.stat(resolvedCookiePath)).mtimeMs;
      if (mtime !== lastCookieMtime) {
        logger.info(
          { oldMtime: lastCookieMtime, newMtime: mtime },
          lastCookieMtime === 0 ? "Loading cookie file" : "Cookie file changed, reloading"
        );
        lastCookieMtime = mtime;
        const newJar = await createCookieJar();
        cookieJar = newJar;
        fetch = wrapWithAuthRetry(newJar ? fetchCookie(nodeFetch, newJar) : nodeFetch, defaultAuthRetryConfig());
        initialSessionRequestMade = false;
      }
    } catch {
      // File deleted or inaccessible - clear cached cookies
      if (cookieJar) {
        logger.info("Cookie file removed, clearing cached cookies");
        cookieJar = null;
        fetch = wrapWithAuthRetry(nodeFetch, defaultAuthRetryConfig());
        lastCookieMtime = 0;
        initialSessionRequestMade = false;
      }
    }
  })();

  try {
    await cookieReloadLock;
  } finally {
    cookieReloadLock = null;
  }
}

async function ensureSessionForRequest(): Promise<void> {
  if (!resolvedCookiePath) return;

  await reloadCookiesIfChanged();

  if (!cookieJar || initialSessionRequestMade) return;

  try {
    const response = await fetch(`${getEffectiveApiUrl()}/user`, {
      ...getFetchConfig(),
      redirect: "follow",
    });
    // 401 means auth failed but the request completed - cookies were still exchanged
    initialSessionRequestMade = response.ok || response.status === 401;
  } catch {
    logger.debug("Session warmup request failed, will retry on next request");
  }
}

// Session auth context for remote authorization
interface SessionAuth {
  sessionId: string;
  header: "Authorization" | "Private-Token" | "JOB-TOKEN";
  token: string;
  lastUsed: number;
  apiUrl: string; // The API URL for the current request
}

interface AuthData {
  header: "Authorization" | "Private-Token" | "JOB-TOKEN";
  token: string;
  lastUsed: number;
  apiUrl: string;
}

const sessionAuthStore = new AsyncLocalStorage<SessionAuth>();

// Session context map for storing auth data by session ID
// This survives async boundaries where AsyncLocalStorage might not
const authBySession: Record<string, AuthData> = {};

// Base headers without authentication
const BASE_HEADERS: Record<string, string> = {
  Accept: "application/json",
  "Content-Type": "application/json",
};

/**
 * Build authentication headers dynamically based on context
 * In REMOTE_AUTHORIZATION or GITLAB_MCP_OAUTH mode, reads from AsyncLocalStorage session context
 * Otherwise, uses environment token (OAuth token is refreshed lazily before each tool call)
 */
function buildAuthHeaders(): Record<string, string> {
  if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
    const ctx = sessionAuthStore.getStore();
    logger.debug({ context: ctx }, "buildAuthHeaders: session context");
    if (ctx?.token) {
      return {
        [ctx.header]: ctx.header === "Authorization" ? `Bearer ${ctx.token}` : ctx.token,
      };
    }
    return {}; // No auth headers if no session context
  }

  // Standard mode: PAT preferred over job token (broader permissions).
  // OAuth token takes priority over PAT when both are set.
  // NOTE: Changed in PR #400 — previously GITLAB_JOB_TOKEN had highest priority.
  // If both GITLAB_PERSONAL_ACCESS_TOKEN and GITLAB_JOB_TOKEN are set, PAT wins.
  const token = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN;

  if (IS_OLD && token) {
    return { "Private-Token": String(token) };
  }
  if (token) {
    return { Authorization: `Bearer ${token}` };
  }

  // Fall back to CI job token
  if (GITLAB_JOB_TOKEN) {
    return { "JOB-TOKEN": String(GITLAB_JOB_TOKEN) };
  }

  return {};
}

/**
 * Get the effective GitLab API URL for the current request
 * In REMOTE_AUTHORIZATION mode with ENABLE_DYNAMIC_API_URL, reads from session context
 * Otherwise, uses environment GITLAB_API_URL
 */
function getEffectiveApiUrl(): string {
  if (ENABLE_DYNAMIC_API_URL) {
    const ctx = sessionAuthStore.getStore();
    if (ctx?.apiUrl) {
      return ctx.apiUrl;
    }
    logger.warn({ ctx }, "getEffectiveApiUrl: No context or apiUrl found, falling back to default");
  }
  return GITLAB_API_URL;
}

/**
 * Get fetch configuration with proper client from pool
 * Uses connection pooling when dynamic API URLs are enabled
 */

/**
 * Constructs the fetch configuration dynamically.
 * This function is called immediately before each `fetch` to ensure it runs
 * within the correct AsyncLocalStorage context, capturing the necessary auth
 * and API URL information for the current request.
 */
const getFetchConfig = () => {
  const effectiveApiUrl = getEffectiveApiUrl();
  const agent = clientPool.getAgentFunctionForUrl(effectiveApiUrl);

  return {
    headers: { ...BASE_HEADERS, ...buildAuthHeaders() },
    agent: agent,
  };
};


// Compute at startup
const enabledToolsets = parseEnabledToolsets(GITLAB_TOOLSETS_RAW);
const individuallyEnabledTools = parseIndividualTools(GITLAB_TOOLS_RAW);
const featureFlagOverrides = buildFeatureFlagOverrides();

// Warn about potentially confusing configuration
if (GITLAB_TOOLSETS_RAW && (USE_PIPELINE || USE_MILESTONE || USE_GITLAB_WIKI)) {
  logger.warn(
    "GITLAB_TOOLSETS is set alongside legacy flags (USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI). " +
    "Legacy flags add tools additively on top of the toolset selection and may produce unexpected results."
  );
}

const MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT = 10;

type GitLabMergeRequestDeploymentSummaryRecord = {
  id: string;
  status: string;
  ref?: string;
  sha: string;
  created_at: string;
  updated_at?: string;
  finished_at?: string | null;
  web_url?: string;
  environment?: {
    id?: string;
    name: string;
    slug?: string;
    external_url?: string | null;
    state?: string;
    tier?: string;
  };
  deployable?: {
    id?: string;
    name?: string;
    status?: string;
    stage?: string;
    web_url?: string;
    pipeline?: {
      id?: string;
      status?: string;
      ref?: string;
      sha?: string;
      web_url?: string;
    };
  } | null;
};

type GitLabMergeRequestWithDeploymentSummary = GitLabMergeRequest & {
  deployment_summary: {
    lookup_sha: string | null;
    sort: "created_at_desc";
    limit: number;
    total_count: number;
    returned_count: number;
    records: GitLabMergeRequestDeploymentSummaryRecord[];
    unavailable_reason?: string;
  };
  commit_addition_summary: {
    target_branch: string;
    source_commits_count: number | null;
    merge_method: string | null;
    merge_commit_count: number | null;
    summary: string | null;
    unavailable_reason?: string;
  };
  approval_summary: {
    approved: boolean | null;
    user_has_approved: boolean | null;
    user_can_approve: boolean | null;
    approved_by: GitLabApprovalUser[];
    approved_by_usernames: string[];
    rules_count: number | null;
    source_endpoint: "approval_state" | "approvals" | null;
    unavailable_reason?: string;
  };
};



// Use the normalizeGitLabApiUrl function to handle various URL formats
const GITLAB_API_URLS = (getConfig("api-url", "GITLAB_API_URL") || "https://gitlab.com")
  .split(",")
  .map(normalizeGitLabApiUrl);
const GITLAB_API_URL = GITLAB_API_URLS[0];
const GITLAB_PROJECT_ID = process.env.GITLAB_PROJECT_ID;
const GITLAB_ALLOWED_PROJECT_IDS =
  process.env.GITLAB_ALLOWED_PROJECT_IDS?.split(",")
    .map(id => id.trim())
    .filter(Boolean) || [];

const GITLAB_COMMIT_FILES_PER_PAGE = process.env.GITLAB_COMMIT_FILES_PER_PAGE
  ? Number.parseInt(process.env.GITLAB_COMMIT_FILES_PER_PAGE, 10)
  : 20;

const GITLAB_REPO_FILE_ENCODING =
  getConfig("repo-file-encoding", "GITLAB_REPO_FILE_ENCODING", "text") === "base64"
    ? "base64"
    : "text";

// Validate authentication configuration
if (REMOTE_AUTHORIZATION) {
  // Remote authorization mode: token comes from HTTP headers
  if (SSE) {
    logger.error("REMOTE_AUTHORIZATION=true is not compatible with SSE transport mode");
    logger.error("Please use STREAMABLE_HTTP=true instead");
    process.exit(1);
  }
  if (!STREAMABLE_HTTP) {
    logger.error("REMOTE_AUTHORIZATION=true requires STREAMABLE_HTTP=true");
    logger.error("Set STREAMABLE_HTTP=true to enable remote authorization");
    process.exit(1);
  }
  logger.info("Remote authorization enabled: tokens will be read from HTTP headers");
}

if (GITLAB_MCP_OAUTH) {
  if (SSE) {
    logger.error("GITLAB_MCP_OAUTH=true is not compatible with SSE transport mode");
    logger.error("Please use STREAMABLE_HTTP=true instead");
    process.exit(1);
  }
  if (!STREAMABLE_HTTP) {
    logger.error("GITLAB_MCP_OAUTH=true requires STREAMABLE_HTTP=true");
    logger.error("Set STREAMABLE_HTTP=true to enable MCP OAuth");
    process.exit(1);
  }
  logger.info("MCP OAuth enabled: GitLab OAuth proxy active (Private-Token/JOB-TOKEN headers bypass OAuth)");
}

if (!REMOTE_AUTHORIZATION && !GITLAB_MCP_OAUTH && !USE_OAUTH && !GITLAB_PERSONAL_ACCESS_TOKEN && !GITLAB_JOB_TOKEN && !GITLAB_AUTH_COOKIE_PATH) {
  // Standard mode: token must be in environment (unless using OAuth)
  logger.error("GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not set");
  logger.info("Either set GITLAB_PERSONAL_ACCESS_TOKEN or enable OAuth with GITLAB_USE_OAUTH=true");
  process.exit(1);
}

/**
 * Utility function for handling GitLab API errors
 * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
 *
 * @param {import("node-fetch").Response} response - The response from GitLab API
 * @throws {Error} Throws an error with response details if the request failed
 */
async function handleGitLabError(response: import("node-fetch").Response): Promise<void> {
  if (!response.ok) {
    const errorBody = await response.text();
    // Check specifically for Rate Limit error
    if (response.status === 403 && errorBody.includes("User API Key Rate limit exceeded")) {
      logger.error("GitLab API Rate Limit Exceeded:", errorBody);
      logger.error("User API Key Rate limit exceeded. Please try again later.");
      throw new Error(`GitLab API Rate Limit Exceeded: ${errorBody}`);
    } else {
      // Handle other API errors
      throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
    }
  }
}

/**
 * @param {string} projectId - The project ID parameter passed to the function
 * @returns {string} The project ID to use for the API call
 * @throws {Error} If GITLAB_ALLOWED_PROJECT_IDS is set and the requested project is not in the whitelist
 */
function getEffectiveProjectId(projectId: string): string {
  if (GITLAB_ALLOWED_PROJECT_IDS.length > 0) {
    // If there's only one allowed project, use it as default
    if (GITLAB_ALLOWED_PROJECT_IDS.length === 1 && !projectId) {
      return GITLAB_ALLOWED_PROJECT_IDS[0];
    }

    // If a project ID is provided, check if it's in the whitelist
    if (projectId && !GITLAB_ALLOWED_PROJECT_IDS.includes(projectId)) {
      throw new Error(
        `Access denied: Project ${projectId} is not in the allowed project list: ${GITLAB_ALLOWED_PROJECT_IDS.join(", ")}`
      );
    }

    // If no project ID provided but we have multiple allowed projects, require an explicit choice
    if (!projectId && GITLAB_ALLOWED_PROJECT_IDS.length > 1) {
      throw new Error(
        `Multiple projects allowed (${GITLAB_ALLOWED_PROJECT_IDS.join(", ")}). Please specify a project ID.`
      );
    }

    return projectId || GITLAB_ALLOWED_PROJECT_IDS[0];
  }
  // Prioritize the passed projectId over GITLAB_PROJECT_ID to allow querying different projects
  if (projectId) {
    return projectId;
  }
  if (GITLAB_PROJECT_ID) {
    return GITLAB_PROJECT_ID;
  }
  throw new Error("No project ID provided and GITLAB_PROJECT_ID is not set");
}

/**
 * Create a fork of a GitLab project
 * 프로젝트 포크 생성 (Create a project fork)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} [namespace] - The namespace to fork the project to
 * @returns {Promise<GitLabFork>} The created fork
 */
async function forkProject(projectId: string, namespace?: string): Promise<GitLabFork> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/fork`
  );

  if (namespace) {
    url.searchParams.append("namespace", namespace);
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });

  // Handle case where project already exists
  if (response.status === 409) {
    throw new Error("Project already exists in the target namespace");
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabForkSchema.parse(data);
}

/**
 * Create a new branch in a GitLab project
 * 새로운 브랜치 생성 (Create a new branch)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {z.infer<typeof CreateBranchOptionsSchema>} options - Branch creation options
 * @returns {Promise<GitLabReference>} The created branch reference
 */
async function createBranch(
  projectId: string,
  options: z.infer<typeof CreateBranchOptionsSchema>
): Promise<GitLabReference> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/branches`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({
      branch: options.name,
      ref: options.ref,
    }),
  });

  await handleGitLabError(response);
  return GitLabReferenceSchema.parse(await response.json());
}

/**
 * Get the default branch for a GitLab project
 * 프로젝트의 기본 브랜치 조회 (Get the default branch of a project)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @returns {Promise<string>} The name of the default branch
 */
async function getDefaultBranchRef(projectId: string): Promise<string> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}`);

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const project = GitLabRepositorySchema.parse(await response.json());
  return project.default_branch ?? "main";
}

/**
 * Get the contents of a file from a GitLab project
 * 파일 내용 조회 (Get file contents)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} filePath - The path of the file to get
 * @param {string} [ref] - The name of the branch, tag or commit
 * @returns {Promise<GitLabContent>} The file content
 */
async function getFileContents(
  projectId: string | undefined,
  filePath: string,
  ref?: string
): Promise<GitLabContent> {
  const decodedProjectId = projectId ? decodeURIComponent(projectId) : "";
  const effectiveProjectId = getEffectiveProjectId(decodedProjectId);
  const encodedPath = encodeURIComponent(filePath);

  // Fall back to default branch if ref is not provided
  if (!ref) {
    ref = await getDefaultBranchRef(decodedProjectId);
  }

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/files/${encodedPath}`
  );

  url.searchParams.append("ref", ref);

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  // Handle file not found
  if (response.status === 404) {
    throw new Error(`File not found: ${filePath}`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  const parsedData = GitLabContentSchema.parse(data);

  // Decode Base64-encoded file content to UTF-8
  if (!Array.isArray(parsedData) && parsedData.content) {
    parsedData.content = Buffer.from(parsedData.content, "base64").toString("utf8");
    parsedData.encoding = "utf8";
  }

  return parsedData;
}

async function createIssue(
  projectId: string,
  options: z.infer<typeof CreateIssueOptionsSchema>
): Promise<GitLabIssue> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/issues`
  );

  // Build request body, converting labels array to comma-separated string
  const body: Record<string, any> = { ...options };
  if (body.labels && Array.isArray(body.labels)) {
    body.labels = body.labels.join(",");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(body),
  });

  // Handle bad request
  if (response.status === 400) {
    const errorBody = await response.text();
    throw new Error(`Invalid request: ${errorBody}`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabIssueSchema.parse(data);
}

/**
 * List issues across all accessible projects or within a specific project
 * 프로젝트의 이슈 목록 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project (optional)
 * @param {Object} options - Options for listing issues
 * @returns {Promise<GitLabIssue[]>} List of issues
 */
async function listIssues(
  projectId?: string,
  options: Omit<z.infer<typeof ListIssuesSchema>, "project_id"> = {}
): Promise<GitLabIssue[]> {
  let url: URL;
  if (projectId) {
    projectId = decodeURIComponent(projectId); // Decode project ID
    const effectiveProjectId = getEffectiveProjectId(projectId);
    url = new URL(
      `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/issues`
    );
  } else {
    url = new URL(`${getEffectiveApiUrl()}/issues`);
  }

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      const keys = ["labels", "assignee_username"];
      if (keys.includes(key)) {
        if (Array.isArray(value)) {
          // Handle array of labels
          value.forEach(label => {
            url.searchParams.append(`${key}[]`, label.toString());
          });
        } else if (value) {
          url.searchParams.append(`${key}[]`, value.toString());
        }
      } else {
        url.searchParams.append(key, String(value));
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabIssueSchema).parse(data);
}

/**
 * List merge requests globally or for a specific GitLab project
 *
 * @param {string} [projectId] - The ID or URL-encoded path of the project.
 *                               If omitted, lists MRs assigned to the authenticated user by default.
 * @param {Object} options - Optional filtering parameters
 * @returns {Promise<GitLabMergeRequest[]>} List of merge requests
 */
async function listMergeRequests(
  projectId?: string,
  options: Omit<z.infer<typeof ListMergeRequestsSchema>, "project_id"> = {}
): Promise<GitLabMergeRequest[]> {
  const decodedProjectId = projectId ? decodeURIComponent(projectId) : undefined;
  const endpoint = decodedProjectId
    ? `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(decodedProjectId))}/merge_requests`
    : `${getEffectiveApiUrl()}/merge_requests`;
  const url = new URL(endpoint);

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (key === "labels" && Array.isArray(value)) {
        // Handle array of labels
        url.searchParams.append(key, value.join(","));
      } else {
        url.searchParams.append(key, String(value));
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabMergeRequestSchema).parse(data);
}

/**
 * Get a single issue from a GitLab project
 * 단일 이슈 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @returns {Promise<GitLabIssue>} The issue
 */
async function getIssue(projectId: string, issueIid: number | string): Promise<GitLabIssue> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabIssueSchema.parse(data);
}

/**
 * Update an issue in a GitLab project
 * 이슈 업데이트
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @param {Object} options - Update options for the issue
 * @returns {Promise<GitLabIssue>} The updated issue
 */
async function updateIssue(
  projectId: string,
  issueIid: number | string,
  options: Omit<z.infer<typeof UpdateIssueSchema>, "project_id" | "issue_iid">
): Promise<GitLabIssue> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}`
  );

  // Convert labels array to comma-separated string if present
  const body: Record<string, any> = { ...options };
  if (body.labels && Array.isArray(body.labels)) {
    body.labels = body.labels.join(",");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(body),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabIssueSchema.parse(data);
}

/**
 * Delete an issue from a GitLab project
 * 이슈 삭제
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @returns {Promise<void>}
 */
async function deleteIssue(projectId: string, issueIid: number | string): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });

  await handleGitLabError(response);
}

// --- GraphQL helper ---

/**
 * Execute a GraphQL query against the GitLab instance.
 * Reusable helper for work item operations.
 */
async function executeGraphQL<T = any>(
  query: string,
  variables: Record<string, any> = {}
): Promise<T> {
  const apiUrl = new URL(getEffectiveApiUrl());
  const restPath = apiUrl.pathname || "";
  const idx = restPath.lastIndexOf("/api/v4");
  const prefix = idx >= 0 ? restPath.slice(0, idx) : "";
  const graphqlUrl =
    process.env.GITLAB_GRAPHQL_URL || `${apiUrl.origin}${prefix}/api/graphql`;

  const response = await fetch(graphqlUrl, {
    ...getFetchConfig(),
    method: "POST",
    headers: {
      ...BASE_HEADERS,
      ...buildAuthHeaders(),
    },
    body: JSON.stringify({ query, variables }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GraphQL request failed (${response.status}): ${errorBody}`);
  }

  const json: any = await response.json();
  if (json.errors && json.errors.length > 0) {
    throw new Error(`GraphQL errors: ${json.errors.map((e: any) => e.message).join(", ")}`);
  }
  return json.data as T;
}

/**
 * Resolve a project path and issue IID to a work item GraphQL GID.
 */
async function resolveWorkItemGID(
  projectId: string,
  issueIid: number
): Promise<{ workItemGID: string; projectPath: string }> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);

  // First get the project path via REST (needed for GraphQL namespace query)
  const projectUrl = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}`
  );
  const projectResponse = await fetch(projectUrl.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(projectResponse);
  const project: any = await projectResponse.json();
  const projectPath: string = project.path_with_namespace;

  // Resolve work item GID via GraphQL
  const data = await executeGraphQL<{
    namespace: { workItem: { id: string } | null };
  }>(
    `query($path: ID!, $iid: String!) {
      namespace(fullPath: $path) {
        workItem(iid: $iid) {
          id
        }
      }
    }`,
    { path: projectPath, iid: String(issueIid) }
  );

  if (!data.namespace?.workItem?.id) {
    throw new Error(`Work item #${issueIid} not found in project ${projectPath}`);
  }

  return { workItemGID: data.namespace.workItem.id, projectPath };
}

/**
 * Resolve label names and usernames to GitLab GIDs in a single GraphQL call.
 */
async function resolveNamesToIds(
  projectPath: string,
  labelNames?: string[],
  usernames?: string[]
): Promise<{ labelIds: string[]; userIds: string[] }> {
  if (!labelNames?.length && !usernames?.length) {
    return { labelIds: [], userIds: [] };
  }
  const data = await executeGraphQL<{
    project: { labels: { nodes: Array<{ id: string; title: string }> } };
    users: { nodes: Array<{ id: string; username: string }> };
  }>(
    `query($path: ID!, $usernames: [String!]!) {
      project(fullPath: $path) { labels(includeAncestorGroups: true, first: 250) { nodes { id title } } }
      users(usernames: $usernames) { nodes { id username } }
    }`,
    { path: projectPath, usernames: usernames || [] }
  );
  const labelIds = (labelNames || []).map(name => {
    const label = data.project.labels.nodes.find(l => l.title === name);
    if (!label) throw new Error(`Label '${name}' not found in project`);
    return label.id;
  });
  const userIds = (usernames || []).map(name => {
    const user = data.users.nodes.find(u => u.username === name);
    if (!user) throw new Error(`User '${name}' not found`);
    return user.id;
  });
  return { labelIds, userIds };
}

// --- Work item type conversion ---

/**
 * Map user-facing type names to GitLab WorkItemType names for GraphQL queries.
 */
const WORK_ITEM_TYPE_NAMES: Record<string, string> = {
  issue: "Issue",
  task: "Task",
  incident: "Incident",
  test_case: "Test Case",
  epic: "Epic",
  key_result: "Key Result",
  objective: "Objective",
  requirement: "Requirement",
  ticket: "Ticket",
};

/**
 * Get the GraphQL GID for a work item type by querying the project's available types.
 */
async function resolveWorkItemTypeGID(
  projectPath: string,
  typeName: string
): Promise<string> {
  const targetName = WORK_ITEM_TYPE_NAMES[typeName];
  if (!targetName) {
    throw new Error(`Unknown work item type: ${typeName}`);
  }

  const data = await executeGraphQL<{
    namespace: { workItemTypes: { nodes: Array<{ id: string; name: string }> } };
  }>(
    `query($path: ID!) {
      namespace(fullPath: $path) {
        workItemTypes {
          nodes {
            id
            name
          }
        }
      }
    }`,
    { path: projectPath }
  );

  const typeNode = data.namespace?.workItemTypes?.nodes?.find(
    (n) => n.name === targetName
  );
  if (!typeNode) {
    throw new Error(
      `Work item type '${targetName}' not found in project ${projectPath}`
    );
  }
  return typeNode.id;
}

/**
 * Convert an issue to a different work item type using GraphQL.
 */
async function convertIssueType(
  projectId: string,
  issueIid: number,
  newType: string
): Promise<{ id: string; type: string }> {
  const { workItemGID, projectPath } = await resolveWorkItemGID(projectId, issueIid);
  const workItemTypeGID = await resolveWorkItemTypeGID(projectPath, newType);

  const data = await executeGraphQL<{
    workItemConvert: {
      workItem: { id: string; workItemType: { name: string } } | null;
      errors: string[];
    };
  }>(
    `mutation($id: WorkItemID!, $typeId: WorkItemsTypeID!) {
      workItemConvert(input: { id: $id, workItemTypeId: $typeId }) {
        workItem {
          id
          workItemType { name }
        }
        errors
      }
    }`,
    { id: workItemGID, typeId: workItemTypeGID }
  );

  if (data.workItemConvert.errors?.length > 0) {
    throw new Error(`Conversion failed: ${data.workItemConvert.errors.join(", ")}`);
  }

  return {
    id: data.workItemConvert.workItem!.id,
    type: data.workItemConvert.workItem!.workItemType.name,
  };
}

// --- Work item hierarchy ---

/**
 * Remove the parent from a work item.
 */
async function removeIssueParent(
  projectId: string,
  issueIid: number
): Promise<void> {
  const { workItemGID } = await resolveWorkItemGID(projectId, issueIid);

  const data = await executeGraphQL<{
    workItemUpdate: {
      workItem: { id: string } | null;
      errors: string[];
    };
  }>(
    `mutation($id: WorkItemID!) {
      workItemUpdate(input: { id: $id, hierarchyWidget: { parentId: null } }) {
        workItem { id }
        errors
      }
    }`,
    { id: workItemGID }
  );

  if (data.workItemUpdate.errors?.length > 0) {
    throw new Error(`Failed to remove parent: ${data.workItemUpdate.errors.join(", ")}`);
  }
}

// --- Work item status ---

/**
 * List available statuses for a work item type in a project.
 * Requires Premium/Ultimate with configurable statuses enabled.
 */
async function listIssueStatuses(
  projectId: string,
  workItemType: string = "issue"
): Promise<any> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);

  // Get project path
  const projectUrl = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}`
  );
  const projectResponse = await fetch(projectUrl.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(projectResponse);
  const project: any = await projectResponse.json();

  const typeName = WORK_ITEM_TYPE_NAMES[workItemType] || "Issue";

  const data = await executeGraphQL<{
    namespace: {
      workItemTypes: {
        nodes: Array<{
          id: string;
          name: string;
          supportedConversionTypes: Array<{ id: string; name: string }>;
          widgetDefinitions: Array<any>;
        }>;
      };
    };
  }>(
    `query($path: ID!, $typeName: IssueType) {
      namespace(fullPath: $path) {
        workItemTypes(name: $typeName) {
          nodes {
            id
            name
            supportedConversionTypes { id name }
            widgetDefinitions {
              __typename
              ... on WorkItemWidgetDefinitionStatus {
                allowedStatuses {
                  id
                  name
                  iconName
                  color
                  position
                }
              }
              ... on WorkItemWidgetDefinitionHierarchy {
                allowedChildTypes { nodes { id name } }
                allowedParentTypes { nodes { id name } }
              }
            }
          }
        }
      }
    }`,
    { path: project.path_with_namespace, typeName: typeName.replace(/ /g, "_").toUpperCase() }
  );

  const typeNodes = data.namespace?.workItemTypes?.nodes;
  if (!typeNodes || typeNodes.length === 0) {
    throw new Error(`Work item type '${typeName}' not found in project`);
  }

  const typeNode = typeNodes[0];

  // Extract statuses from the status widget definition
  const statusWidget = typeNode.widgetDefinitions?.find(
    (w: any) => w.__typename === "WorkItemWidgetDefinitionStatus"
  );
  const statuses = statusWidget?.allowedStatuses || [];

  // Extract hierarchy info
  const hierarchyWidget = typeNode.widgetDefinitions?.find(
    (w: any) => w.__typename === "WorkItemWidgetDefinitionHierarchy"
  );

  const result: Record<string, any> = {
    work_item_type: typeNode.name,
    statuses_available: statuses.length > 0,
    statuses,
  };

  // Add supported conversion types
  const conversionTypes = typeNode.supportedConversionTypes || [];
  if (conversionTypes.length > 0) {
    result.supported_conversion_types = conversionTypes.map((t: any) => t.name);
  }

  // Add allowed child/parent types
  const childTypes = hierarchyWidget?.allowedChildTypes?.nodes || [];
  const parentTypes = hierarchyWidget?.allowedParentTypes?.nodes || [];
  if (childTypes.length > 0) {
    result.allowed_child_types = childTypes.map((t: any) => t.name);
  }
  if (parentTypes.length > 0) {
    result.allowed_parent_types = parentTypes.map((t: any) => t.name);
  }

  return result;
}

/**
 * List available custom field definitions for a work item type.
 */
async function listCustomFieldDefinitions(
  projectId: string,
  workItemType: string = "issue"
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);
  const typeName = WORK_ITEM_TYPE_NAMES[workItemType] || "Issue";

  const data = await executeGraphQL<{
    namespace: {
      workItemTypes: {
        nodes: Array<{
          id: string;
          name: string;
          widgetDefinitions: Array<any>;
        }>;
      };
    };
  }>(
    `query($path: ID!, $typeName: IssueType) {
      namespace(fullPath: $path) {
        workItemTypes(name: $typeName) {
          nodes {
            id
            name
            widgetDefinitions {
              __typename
              ... on WorkItemWidgetDefinitionCustomFields {
                customFieldValues {
                  customField {
                    id
                    name
                    fieldType
                    selectOptions { id value }
                    workItemTypes { id name }
                  }
                }
              }
            }
          }
        }
      }
    }`,
    { path: projectPath, typeName: typeName.replace(/ /g, "_").toUpperCase() }
  );

  const typeNodes = data.namespace?.workItemTypes?.nodes;
  if (!typeNodes || typeNodes.length === 0) {
    throw new Error(`Work item type '${typeName}' not found in project`);
  }

  const typeNode = typeNodes[0];
  const customFieldsWidget = typeNode.widgetDefinitions?.find(
    (w: any) => w.__typename === "WorkItemWidgetDefinitionCustomFields"
  );

  const fields = (customFieldsWidget?.customFieldValues || []).map((cfv: any) => {
    const cf = cfv.customField;
    const field: Record<string, any> = {
      id: cf?.id,
      name: cf?.name,
      type: cf?.fieldType,
    };
    const options = cf?.selectOptions || [];
    if (options.length > 0) field.selectOptions = options;
    const types = (cf?.workItemTypes || []).map((t: any) => t.name);
    if (types.length > 0) field.workItemTypes = types;
    return field;
  });

  return {
    work_item_type: typeNode.name,
    custom_fields: fields,
  };
}

/**
 * Move a work item to a different project.
 */
async function moveWorkItem(
  projectId: string,
  iid: number,
  targetProjectId: string
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);
  const targetPath = await resolveProjectPath(targetProjectId);

  const data = await executeGraphQL<{
    issueMove: {
      issue: { id: string; iid: string; webUrl: string } | null;
      errors: string[];
    };
  }>(
    `mutation($projectPath: ID!, $iid: String!, $targetProjectPath: ID!) {
      issueMove(input: { projectPath: $projectPath, iid: $iid, targetProjectPath: $targetProjectPath }) {
        issue { id iid webUrl }
        errors
      }
    }`,
    { projectPath: projectPath, iid: String(iid), targetProjectPath: targetPath }
  );

  if (data.issueMove.errors?.length > 0) {
    throw new Error(`Failed to move work item: ${data.issueMove.errors.join(", ")}`);
  }

  return data.issueMove.issue;
}

/**
 * List notes/discussions on a work item.
 */
async function listWorkItemNotes(
  projectId: string,
  iid: number,
  options: { page_size?: number; after?: string; sort?: string } = {}
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);

  const data = await executeGraphQL<{ namespace: any }>(
    `query($path: ID!, $iid: String!, $pageSize: Int, $after: String, $sort: WorkItemDiscussionsSort) {
      namespace(fullPath: $path) {
        workItem(iid: $iid) {
          id
          widgets(onlyTypes: [NOTES]) {
            ... on WorkItemWidgetNotes {
              discussionLocked
              discussions(first: $pageSize, after: $after, filter: ALL_NOTES, sort: $sort) {
                pageInfo { hasNextPage endCursor }
                nodes {
                  id
                  resolved
                  resolvable
                  notes {
                    nodes {
                      id
                      body
                      system
                      internal
                      createdAt
                      lastEditedAt
                      author { username }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }`,
    {
      path: projectPath,
      iid: String(iid),
      pageSize: options.page_size || 20,
      after: options.after || null,
      sort: options.sort || "CREATED_ASC",
    }
  );

  const workItem = data.namespace?.workItem;
  if (!workItem) {
    throw new Error(`Work item #${iid} not found in project ${projectPath}`);
  }

  const notesWidget = workItem.widgets?.find((w: any) => w.discussions);
  const discussions = notesWidget?.discussions;

  // Flatten to lean output
  const items = (discussions?.nodes || []).map((d: any) => {
    const notes = (d.notes?.nodes || []).map((n: any) => {
      const note: Record<string, any> = {
        id: n.id,
        author: n.author?.username,
        body: n.body,
        createdAt: n.createdAt,
      };
      if (n.system) note.system = true;
      if (n.internal) note.internal = true;
      if (n.lastEditedAt) note.lastEditedAt = n.lastEditedAt;
      return note;
    });
    const discussion: Record<string, any> = { id: d.id, notes };
    if (d.resolved) discussion.resolved = true;
    if (d.resolvable) discussion.resolvable = true;
    return discussion;
  });

  return {
    discussions: items,
    pageInfo: discussions?.pageInfo || {},
  };
}

/**
 * Create a note on a work item.
 */
async function createWorkItemNote(
  projectId: string,
  iid: number,
  body: string,
  options: { internal?: boolean; discussion_id?: string } = {}
): Promise<any> {
  const { workItemGID } = await resolveWorkItemGID(projectId, iid);

  const varDefs = ["$noteableId: NoteableID!", "$body: String!"];
  const inputParts = ["noteableId: $noteableId", "body: $body"];
  const variables: Record<string, any> = { noteableId: workItemGID, body };

  if (options.internal) {
    varDefs.push("$internal: Boolean");
    inputParts.push("internal: $internal");
    variables.internal = true;
  }

  if (options.discussion_id) {
    varDefs.push("$discussionId: DiscussionID");
    inputParts.push("discussionId: $discussionId");
    variables.discussionId = options.discussion_id;
  }

  const data = await executeGraphQL<{
    createNote: {
      note: { id: string; body: string; discussion: { id: string } } | null;
      errors: string[];
    };
  }>(
    `mutation(${varDefs.join(", ")}) {
      createNote(input: { ${inputParts.join(", ")} }) {
        note {
          id
          body
          discussion { id }
        }
        errors
      }
    }`,
    variables
  );

  if (data.createNote.errors?.length > 0) {
    throw new Error(`Failed to create note: ${data.createNote.errors.join(", ")}`);
  }

  return data.createNote.note;
}

// --- Incident Timeline Events ---

/**
 * List timeline events for an incident.
 */
async function getTimelineEvents(
  projectId: string,
  incidentIid: number
): Promise<any> {
  const { workItemGID, projectPath } = await resolveWorkItemGID(projectId, incidentIid);
  // Timeline events expect gid://gitlab/Issue/... not gid://gitlab/WorkItem/...
  const incidentGID = workItemGID.replace("/WorkItem/", "/Issue/");

  const data = await executeGraphQL<{ project: any }>(
    `query($fullPath: ID!, $incidentId: IssueID!) {
      project(fullPath: $fullPath) {
        incidentManagementTimelineEvents(incidentId: $incidentId) {
          nodes {
            id
            note
            noteHtml
            action
            occurredAt
            createdAt
            timelineEventTags {
              nodes {
                id
                name
              }
            }
          }
        }
      }
    }`,
    { fullPath: projectPath, incidentId: incidentGID }
  );

  const events = data.project?.incidentManagementTimelineEvents?.nodes || [];

  return events.map((e: any) => {
    const event: Record<string, any> = {
      id: e.id,
      note: e.note,
      action: e.action,
      occurredAt: e.occurredAt,
      createdAt: e.createdAt,
    };
    if (e.noteHtml) event.noteHtml = e.noteHtml;
    const tags = (e.timelineEventTags?.nodes || []).map((t: any) => t.name);
    if (tags.length > 0) event.tags = tags;
    return event;
  });
}

/**
 * Create a timeline event on an incident.
 */
async function createTimelineEvent(
  projectId: string,
  incidentIid: number,
  note: string,
  occurredAt: string,
  tagNames?: string[]
): Promise<any> {
  const { workItemGID } = await resolveWorkItemGID(projectId, incidentIid);
  // Timeline events expect gid://gitlab/Issue/... not gid://gitlab/WorkItem/...
  const incidentGID = workItemGID.replace("/WorkItem/", "/Issue/");

  const variables: Record<string, any> = {
    input: {
      incidentId: incidentGID,
      note,
      occurredAt,
    },
  };
  if (tagNames && tagNames.length > 0) {
    variables.input.timelineEventTagNames = tagNames;
  }

  const data = await executeGraphQL<{
    timelineEventCreate: {
      timelineEvent: any;
      errors: string[];
    };
  }>(
    `mutation CreateTimelineEvent($input: TimelineEventCreateInput!) {
      timelineEventCreate(input: $input) {
        timelineEvent {
          id
          note
          noteHtml
          action
          occurredAt
          createdAt
          timelineEventTags {
            nodes {
              id
              name
            }
          }
        }
        errors
      }
    }`,
    variables
  );

  if (data.timelineEventCreate.errors?.length > 0) {
    throw new Error(`Failed to create timeline event: ${data.timelineEventCreate.errors.join(", ")}`);
  }

  const e = data.timelineEventCreate.timelineEvent;
  const result: Record<string, any> = {
    id: e.id,
    note: e.note,
    action: e.action,
    occurredAt: e.occurredAt,
    createdAt: e.createdAt,
  };
  if (e.noteHtml) result.noteHtml = e.noteHtml;
  const tags = (e.timelineEventTags?.nodes || []).map((t: any) => t.name);
  if (tags.length > 0) result.tags = tags;
  return result;
}

/**
 * Update the severity of an incident.
 * Accepts projectPath directly to avoid redundant REST calls when called from updateWorkItem.
 */
async function updateIncidentSeverity(
  projectPath: string,
  incidentIid: number,
  severity: string
): Promise<any> {
  const data = await executeGraphQL<{
    issueSetSeverity: {
      errors: string[];
      issue: { iid: string; id: string; severity: string } | null;
    };
  }>(
    `mutation($projectPath: ID!, $severity: IssuableSeverity!, $iid: String!) {
      issueSetSeverity(input: { iid: $iid, severity: $severity, projectPath: $projectPath }) {
        errors
        issue {
          iid
          id
          severity
        }
      }
    }`,
    { projectPath, severity, iid: String(incidentIid) }
  );

  if (data.issueSetSeverity.errors?.length > 0) {
    throw new Error(`Failed to set severity: ${data.issueSetSeverity.errors.join(", ")}`);
  }

  return data.issueSetSeverity.issue;
}

/**
 * Update the escalation status of an incident.
 * Accepts projectPath directly to avoid redundant REST calls when called from updateWorkItem.
 */
async function updateIncidentEscalationStatus(
  projectPath: string,
  incidentIid: number,
  status: string
): Promise<any> {
  const data = await executeGraphQL<{
    issueSetEscalationStatus: {
      errors: string[];
      issue: { id: string; escalationStatus: string } | null;
    };
  }>(
    `mutation($projectPath: ID!, $status: IssueEscalationStatus!, $iid: String!) {
      issueSetEscalationStatus(input: { projectPath: $projectPath, status: $status, iid: $iid }) {
        errors
        issue {
          id
          escalationStatus
        }
      }
    }`,
    { projectPath, status, iid: String(incidentIid) }
  );

  if (data.issueSetEscalationStatus.errors?.length > 0) {
    throw new Error(`Failed to set escalation status: ${data.issueSetEscalationStatus.errors.join(", ")}`);
  }

  return data.issueSetEscalationStatus.issue;
}

/**
 * Resolve a project ID (numeric or path) to its full path_with_namespace.
 */
async function resolveProjectPath(projectId: string): Promise<string> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const projectUrl = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}`
  );
  const projectResponse = await fetch(projectUrl.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(projectResponse);
  const project: any = await projectResponse.json();
  return project.path_with_namespace;
}

/**
 * Get a single work item with all widget data.
 */
async function getWorkItem(
  projectId: string,
  iid: number
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);

  const data = await executeGraphQL<{
    namespace: { workItem: any };
  }>(
    `query($path: ID!, $iid: String!) {
      namespace(fullPath: $path) {
        workItem(iid: $iid) {
          id
          iid
          title
          state
          description
          webUrl
          confidential
          author { username }
          createdAt
          closedAt
          workItemType { name }
          widgets {
            __typename
            ... on WorkItemWidgetHierarchy {
              hasChildren hasParent
              parent { id iid title webUrl workItemType { name } namespace { fullPath } }
              children { nodes { id iid title state webUrl workItemType { name } namespace { fullPath } } }
            }
            ... on WorkItemWidgetStatus { status { id name category color iconName position } }
            ... on WorkItemWidgetCustomFields {
              customFieldValues {
                __typename
                customField { id name fieldType }
                ... on WorkItemNumberFieldValue { value }
                ... on WorkItemTextFieldValue { value }
                ... on WorkItemSelectFieldValue {
                  selectedOptions { id value }
                }
              }
            }
            ... on WorkItemWidgetLabels { labels { nodes { id title color } } }
            ... on WorkItemWidgetAssignees { assignees { nodes { id username name } } }
            ... on WorkItemWidgetWeight { weight rolledUpWeight rolledUpCompletedWeight }
            ... on WorkItemWidgetHealthStatus { healthStatus }
            ... on WorkItemWidgetStartAndDueDate { startDate dueDate }
            ... on WorkItemWidgetMilestone { milestone { id title } }
            ... on WorkItemWidgetLinkedItems {
              blocked blockedByCount blockingCount
              linkedItems { nodes { linkType workItem { id iid title state webUrl workItemType { name } namespace { fullPath } } } }
            }
            ... on WorkItemWidgetTimeTracking {
              timeEstimate totalTimeSpent
            }
            ... on WorkItemWidgetDevelopment {
              willAutoCloseByMergeRequest
              relatedBranches { nodes { name } }
              relatedMergeRequests {
                nodes { iid title webUrl state sourceBranch }
              }
              closingMergeRequests {
                nodes {
                  mergeRequest { iid title webUrl state sourceBranch }
                }
              }
              featureFlags { nodes { name active } }
            }
            ... on WorkItemWidgetIteration {
              iteration { id title startDate dueDate webUrl iterationCadence { id title } }
            }
            ... on WorkItemWidgetProgress { progress }
            ... on WorkItemWidgetColor { color textColor }
          }
        }
      }
    }`,
    { path: projectPath, iid: String(iid) }
  );

  if (!data.namespace?.workItem) {
    throw new Error(`Work item #${iid} not found in project ${projectPath}`);
  }

  const wi = data.namespace.workItem;
  const widgets = wi.widgets || [];

  // Flatten widget data into a clean response
  const hierarchyWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetHierarchy");
  const statusWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetStatus");
  const labelsWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetLabels");
  const assigneesWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetAssignees");
  const weightWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetWeight");
  const healthStatusWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetHealthStatus");
  const datesWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetStartAndDueDate");
  const milestoneWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetMilestone");
  const linkedItemsWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetLinkedItems");
  const timeTrackingWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetTimeTracking");
  const developmentWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetDevelopment");
  const customFieldsWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetCustomFields");

  // Build response, omitting null/empty values to keep output lean
  const result: Record<string, any> = {
    id: wi.id,
    iid: wi.iid,
    title: wi.title,
    state: wi.state,
    type: wi.workItemType?.name,
    webUrl: wi.webUrl,
  };

  if (wi.description) result.description = wi.description;
  if (wi.confidential) result.confidential = true;
  if (wi.author?.username) result.author = wi.author.username;
  if (wi.createdAt) result.createdAt = wi.createdAt;
  if (wi.closedAt) result.closedAt = wi.closedAt;
  if (statusWidget?.status) result.status = { name: statusWidget.status.name, id: statusWidget.status.id, category: statusWidget.status.category };

  const labels = (labelsWidget?.labels?.nodes || []).map((l: any) => l.title);
  if (labels.length > 0) result.labels = labels;

  const assignees = (assigneesWidget?.assignees?.nodes || []).map((a: any) => a.username);
  if (assignees.length > 0) result.assignees = assignees;

  if (weightWidget?.weight != null) {
    result.weight = weightWidget.weight;
    if (weightWidget.rolledUpWeight != null) result.rolledUpWeight = weightWidget.rolledUpWeight;
    if (weightWidget.rolledUpCompletedWeight != null) result.rolledUpCompletedWeight = weightWidget.rolledUpCompletedWeight;
  }
  if (healthStatusWidget?.healthStatus) result.healthStatus = healthStatusWidget.healthStatus;
  if (datesWidget?.startDate) result.startDate = datesWidget.startDate;
  if (datesWidget?.dueDate) result.dueDate = datesWidget.dueDate;
  if (milestoneWidget?.milestone) result.milestone = { id: milestoneWidget.milestone.id, title: milestoneWidget.milestone.title };

  const iterationWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetIteration");
  if (iterationWidget?.iteration) {
    result.iteration = {
      id: iterationWidget.iteration.id,
      title: iterationWidget.iteration.title,
      startDate: iterationWidget.iteration.startDate,
      dueDate: iterationWidget.iteration.dueDate,
    };
  }

  const progressWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetProgress");
  if (progressWidget?.progress != null) result.progress = progressWidget.progress;

  const colorWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetColor");
  if (colorWidget?.color) result.color = colorWidget.color;

  if (hierarchyWidget?.parent) result.parent = { iid: hierarchyWidget.parent.iid, title: hierarchyWidget.parent.title, type: hierarchyWidget.parent.workItemType?.name, project: hierarchyWidget.parent.namespace?.fullPath, webUrl: hierarchyWidget.parent.webUrl };
  const children = hierarchyWidget?.children?.nodes || [];
  if (children.length > 0) result.children = children.map((c: any) => ({ iid: c.iid, title: c.title, state: c.state, type: c.workItemType?.name, project: c.namespace?.fullPath, webUrl: c.webUrl }));

  if (linkedItemsWidget?.blocked) result.blocked = true;
  if (linkedItemsWidget?.blockedByCount > 0) result.blockedByCount = linkedItemsWidget.blockedByCount;
  if (linkedItemsWidget?.blockingCount > 0) result.blockingCount = linkedItemsWidget.blockingCount;
  const linkedNodes = linkedItemsWidget?.linkedItems?.nodes || [];
  if (linkedNodes.length > 0) {
    result.linkedItems = linkedNodes.map((n: any) => ({
      linkType: n.linkType,
      iid: n.workItem?.iid,
      title: n.workItem?.title,
      state: n.workItem?.state,
      type: n.workItem?.workItemType?.name,
      project: n.workItem?.namespace?.fullPath,
      webUrl: n.workItem?.webUrl,
    }));
  }

  if (timeTrackingWidget?.timeEstimate > 0) result.timeEstimate = timeTrackingWidget.timeEstimate;
  if (timeTrackingWidget?.totalTimeSpent > 0) result.totalTimeSpent = timeTrackingWidget.totalTimeSpent;

  // Development: only include if there's actual data
  const relatedMRs = developmentWidget?.relatedMergeRequests?.nodes || [];
  const closingMRs = (developmentWidget?.closingMergeRequests?.nodes || []).map((n: any) => n.mergeRequest);
  const branches = developmentWidget?.relatedBranches?.nodes || [];
  const flags = developmentWidget?.featureFlags?.nodes || [];
  if (relatedMRs.length > 0 || closingMRs.length > 0 || branches.length > 0 || flags.length > 0) {
    const dev: Record<string, any> = {};
    if (relatedMRs.length > 0) dev.relatedMergeRequests = relatedMRs;
    if (closingMRs.length > 0) dev.closingMergeRequests = closingMRs;
    if (branches.length > 0) dev.relatedBranches = branches.map((b: any) => b.name);
    if (flags.length > 0) dev.featureFlags = flags;
    result.development = dev;
  }

  const cfValues = (customFieldsWidget?.customFieldValues || []).filter((cfv: any) => cfv.value != null || cfv.selectedOptions != null);
  if (cfValues.length > 0) {
    result.customFields = cfValues.map((cfv: any) => ({
      name: cfv.customField?.name,
      type: cfv.customField?.fieldType,
      value: cfv.value ?? cfv.selectedOptions ?? null,
    }));
  }

  return result;
}

/**
 * List work items in a project with filters.
 */
async function listWorkItems(
  projectId: string,
  options: {
    types?: string[];
    state?: string;
    search?: string;
    assignee_usernames?: string[];
    label_names?: string[];
    first?: number;
    after?: string;
  }
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);

  // Map type names to GraphQL enum values
  const typeMap: Record<string, string> = {
    issue: "ISSUE",
    task: "TASK",
    incident: "INCIDENT",
    test_case: "TEST_CASE",
    epic: "EPIC",
    key_result: "KEY_RESULT",
    objective: "OBJECTIVE",
    requirement: "REQUIREMENT",
    ticket: "TICKET",
  };

  const variables: Record<string, any> = {
    path: projectPath,
    first: options.first || 20,
  };

  if (options.types && options.types.length > 0) {
    variables.types = options.types.map((t) => typeMap[t] || t.replace(/ /g, "_").toUpperCase());
  }
  if (options.state) {
    variables.state = options.state === "opened" ? "opened" : "closed";
  }
  if (options.search) {
    variables.search = options.search;
  }
  if (options.assignee_usernames && options.assignee_usernames.length > 0) {
    variables.assigneeUsernames = options.assignee_usernames;
  }
  if (options.label_names && options.label_names.length > 0) {
    variables.labelName = options.label_names;
  }
  if (options.after) {
    variables.after = options.after;
  }

  const data = await executeGraphQL<{ project: any }>(
    `query($path: ID!, $types: [IssueType!], $state: IssuableState, $search: String, $assigneeUsernames: [String!], $labelName: [String!], $first: Int, $after: String) {
      project(fullPath: $path) {
        workItems(types: $types, state: $state, search: $search, assigneeUsernames: $assigneeUsernames, labelName: $labelName, first: $first, after: $after) {
          nodes {
            id iid title state webUrl workItemType { name }
            widgets {
              __typename
              ... on WorkItemWidgetStatus { status { id name category color } }
              ... on WorkItemWidgetLabels { labels { nodes { title } } }
              ... on WorkItemWidgetAssignees { assignees { nodes { username } } }
              ... on WorkItemWidgetWeight { weight }
              ... on WorkItemWidgetHealthStatus { healthStatus }
              ... on WorkItemWidgetStartAndDueDate { startDate dueDate }
              ... on WorkItemWidgetMilestone { milestone { id title } }
            }
          }
          pageInfo { hasNextPage endCursor }
        }
      }
    }`,
    variables
  );

  const workItems = data.project?.workItems?.nodes || [];
  const pageInfo = data.project?.workItems?.pageInfo || {};

  // Flatten widget data for each item
  const items = workItems.map((wi: any) => {
    const widgets = wi.widgets || [];
    const statusWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetStatus");
    const labelsWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetLabels");
    const assigneesWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetAssignees");
    const weightWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetWeight");
    const healthStatusWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetHealthStatus");
    const datesWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetStartAndDueDate");
    const milestoneWidget = widgets.find((w: any) => w.__typename === "WorkItemWidgetMilestone");
    const item: Record<string, any> = {
      iid: wi.iid,
      title: wi.title,
      state: wi.state,
      type: wi.workItemType?.name,
      webUrl: wi.webUrl,
    };
    if (statusWidget?.status) item.status = statusWidget.status.name;
    const labels = (labelsWidget?.labels?.nodes || []).map((l: any) => l.title);
    if (labels.length > 0) item.labels = labels;
    const assignees = (assigneesWidget?.assignees?.nodes || []).map((a: any) => a.username);
    if (assignees.length > 0) item.assignees = assignees;
    if (weightWidget?.weight != null) item.weight = weightWidget.weight;
    if (healthStatusWidget?.healthStatus) item.healthStatus = healthStatusWidget.healthStatus;
    if (datesWidget?.startDate) item.startDate = datesWidget.startDate;
    if (datesWidget?.dueDate) item.dueDate = datesWidget.dueDate;
    if (milestoneWidget?.milestone) item.milestone = milestoneWidget.milestone.title;
    return item;
  });

  return { items, pageInfo };
}

/**
 * Create a new work item using GraphQL.
 */
async function createWorkItem(
  projectId: string,
  options: {
    title: string;
    type?: string;
    description?: string;
    labels?: string[];
    assignee_usernames?: string[];
    parent_iid?: number;
    weight?: number;
    health_status?: string;
    start_date?: string;
    due_date?: string;
    milestone_id?: string;
    iteration_id?: string;
    confidential?: boolean;
  }
): Promise<any> {
  const projectPath = await resolveProjectPath(projectId);
  const typeName = options.type || "issue";
  const typeGID = await resolveWorkItemTypeGID(projectPath, typeName);

  // Build the input dynamically - only include widgets that have values
  const inputFields: string[] = [
    "$projectPath: ID!",
    "$title: String!",
    "$typeId: WorkItemsTypeID!",
  ];
  const inputValues: string[] = [
    "namespacePath: $projectPath",
    "title: $title",
    "workItemTypeId: $typeId",
  ];
  const variables: Record<string, any> = {
    projectPath,
    title: options.title,
    typeId: typeGID,
  };

  if (options.description !== undefined) {
    inputFields.push("$description: String!");
    inputValues.push("descriptionWidget: { description: $description }");
    variables.description = options.description;
  }

  // Resolve label names and usernames to GIDs in a single GraphQL call
  const { labelIds, userIds } = await resolveNamesToIds(
    projectPath,
    options.labels,
    options.assignee_usernames
  );

  if (labelIds.length > 0) {
    inputFields.push("$labelIds: [LabelID!]!");
    inputValues.push("labelsWidget: { labelIds: $labelIds }");
    variables.labelIds = labelIds;
  }

  // Incidents don't support the weight widget
  if (options.weight !== undefined && typeName !== "incident") {
    inputFields.push("$weight: Int");
    inputValues.push("weightWidget: { weight: $weight }");
    variables.weight = options.weight;
  }

  // Resolve parent GID if provided
  if (options.parent_iid !== undefined) {
    const { workItemGID: parentGID } = await resolveWorkItemGID(projectId, options.parent_iid);
    inputFields.push("$parentId: WorkItemID");
    inputValues.push("hierarchyWidget: { parentId: $parentId }");
    variables.parentId = parentGID;
  }

  if (userIds.length > 0) {
    inputFields.push("$assigneeIds: [UserID!]!");
    inputValues.push("assigneesWidget: { assigneeIds: $assigneeIds }");
    variables.assigneeIds = userIds;
  }

  if (options.health_status !== undefined) {
    inputFields.push("$healthStatus: HealthStatus");
    inputValues.push("healthStatusWidget: { healthStatus: $healthStatus }");
    variables.healthStatus = options.health_status;
  }

  // Start and due date widget - combine into one widget
  if (options.start_date !== undefined || options.due_date !== undefined) {
    const dateParts: string[] = [];
    if (options.start_date !== undefined) {
      inputFields.push("$startDate: Date");
      dateParts.push("startDate: $startDate");
      variables.startDate = options.start_date;
    }
    if (options.due_date !== undefined) {
      inputFields.push("$dueDate: Date");
      dateParts.push("dueDate: $dueDate");
      variables.dueDate = options.due_date;
    }
    inputValues.push(`startAndDueDateWidget: { ${dateParts.join(", ")} }`);
  }

  if (options.milestone_id !== undefined) {
    // Convert numeric ID to GID format if needed
    const milestoneGID = options.milestone_id.startsWith("gid://")
      ? options.milestone_id
      : `gid://gitlab/Milestone/${options.milestone_id}`;
    inputFields.push("$milestoneId: MilestoneID");
    inputValues.push("milestoneWidget: { milestoneId: $milestoneId }");
    variables.milestoneId = milestoneGID;
  }

  if (options.iteration_id !== undefined) {
    const iterationGID = options.iteration_id.startsWith("gid://")
      ? options.iteration_id
      : `gid://gitlab/Iteration/${options.iteration_id}`;
    inputFields.push("$iterationId: IterationID");
    inputValues.push("iterationWidget: { iterationId: $iterationId }");
    variables.iterationId = iterationGID;
  }

  if (options.confidential !== undefined) {
    inputFields.push("$confidential: Boolean");
    inputValues.push("confidential: $confidential");
    variables.confidential = options.confidential;
  }

  const mutation = `mutation(${inputFields.join(", ")}) {
    workItemCreate(input: { ${inputValues.join(", ")} }) {
      workItem {
        id
        iid
        title
        webUrl
        workItemType { name }
      }
      errors
    }
  }`;

  const data = await executeGraphQL<{
    workItemCreate: {
      workItem: any;
      errors: string[];
    };
  }>(mutation, variables);

  if (data.workItemCreate.errors?.length > 0) {
    throw new Error(`Failed to create work item: ${data.workItemCreate.errors.join(", ")}`);
  }

  const wi = data.workItemCreate.workItem;
  return {
    id: wi.id,
    iid: wi.iid,
    title: wi.title,
    type: wi.workItemType?.name,
    webUrl: wi.webUrl,
  };
}

/**
 * Update a work item - consolidated handler for title, description, labels, assignees,
 * weight, state, status, parent, and children operations.
 */
async function updateWorkItem(
  projectId: string,
  iid: number,
  options: {
    title?: string;
    description?: string;
    add_labels?: string[];
    remove_labels?: string[];
    assignee_usernames?: string[];
    state_event?: string;
    weight?: number;
    status?: string;
    parent_iid?: number;
    parent_project_id?: string;
    remove_parent?: boolean;
    children_to_add?: Array<{ project_id?: string; iid: number }>;
    children_to_remove?: Array<{ project_id?: string; iid: number }>;
    health_status?: string;
    start_date?: string;
    due_date?: string;
    milestone_id?: string;
    iteration_id?: string;
    confidential?: boolean;
    linked_items_to_add?: Array<{ project_id?: string; iid: number; link_type?: string }>;
    linked_items_to_remove?: Array<{ project_id?: string; iid: number }>;
    custom_fields?: Array<{
      custom_field_id: string;
      text_value?: string;
      number_value?: number;
      selected_option_ids?: string[];
      date_value?: string;
    }>;
    severity?: string;
    escalation_status?: string;
  }
): Promise<any> {
  const { workItemGID, projectPath } = await resolveWorkItemGID(projectId, iid);

  // Build the main workItemUpdate mutation dynamically
  const inputParts: string[] = ["id: $id"];
  const varDefs: string[] = ["$id: WorkItemID!"];
  const variables: Record<string, any> = { id: workItemGID };

  if (options.title !== undefined) {
    varDefs.push("$title: String");
    inputParts.push("title: $title");
    variables.title = options.title;
  }

  if (options.description !== undefined) {
    varDefs.push("$description: String!");
    inputParts.push("descriptionWidget: { description: $description }");
    variables.description = options.description;
  }

  // Resolve label names and usernames to GIDs in a single GraphQL call
  const allLabelNames = [...(options.add_labels || []), ...(options.remove_labels || [])];
  const needsResolve = allLabelNames.length > 0 || options.assignee_usernames?.length;
  const { labelIds: resolvedLabelIds, userIds } = needsResolve
    ? await resolveNamesToIds(
        projectPath,
        allLabelNames.length > 0 ? allLabelNames : undefined,
        options.assignee_usernames
      )
    : { labelIds: [] as string[], userIds: [] as string[] };

  if (options.add_labels || options.remove_labels) {
    const labelParts: string[] = [];
    let offset = 0;

    if (options.add_labels && options.add_labels.length > 0) {
      const addIds = resolvedLabelIds.slice(0, options.add_labels.length);
      offset = options.add_labels.length;
      varDefs.push("$addLabelIds: [LabelID!]");
      labelParts.push("addLabelIds: $addLabelIds");
      variables.addLabelIds = addIds;
    }
    if (options.remove_labels && options.remove_labels.length > 0) {
      const removeIds = resolvedLabelIds.slice(offset);
      varDefs.push("$removeLabelIds: [LabelID!]");
      labelParts.push("removeLabelIds: $removeLabelIds");
      variables.removeLabelIds = removeIds;
    }

    if (labelParts.length > 0) {
      inputParts.push(`labelsWidget: { ${labelParts.join(", ")} }`);
    }
  }

  if (userIds.length > 0) {
    varDefs.push("$assigneeIds: [UserID!]!");
    inputParts.push("assigneesWidget: { assigneeIds: $assigneeIds }");
    variables.assigneeIds = userIds;
  }

  if (options.state_event !== undefined) {
    varDefs.push("$stateEvent: WorkItemStateEvent");
    inputParts.push("stateEvent: $stateEvent");
    variables.stateEvent = options.state_event === "close" ? "CLOSE" : "REOPEN";
  }

  if (options.weight !== undefined) {
    varDefs.push("$weight: Int");
    inputParts.push("weightWidget: { weight: $weight }");
    variables.weight = options.weight;
  }

  if (options.status !== undefined) {
    varDefs.push("$status: WorkItemsStatusesStatusID");
    inputParts.push("statusWidget: { status: $status }");
    variables.status = options.status;
  }

  if (options.health_status !== undefined) {
    varDefs.push("$healthStatus: HealthStatus");
    inputParts.push("healthStatusWidget: { healthStatus: $healthStatus }");
    variables.healthStatus = options.health_status;
  }

  // Start and due date widget - combine into one widget
  if (options.start_date !== undefined || options.due_date !== undefined) {
    const dateParts: string[] = [];
    if (options.start_date !== undefined) {
      varDefs.push("$startDate: Date");
      dateParts.push("startDate: $startDate");
      variables.startDate = options.start_date;
    }
    if (options.due_date !== undefined) {
      varDefs.push("$dueDate: Date");
      dateParts.push("dueDate: $dueDate");
      variables.dueDate = options.due_date;
    }
    inputParts.push(`startAndDueDateWidget: { ${dateParts.join(", ")} }`);
  }

  if (options.milestone_id !== undefined) {
    // Convert numeric ID to GID format if needed
    const milestoneGID = options.milestone_id.startsWith("gid://")
      ? options.milestone_id
      : `gid://gitlab/Milestone/${options.milestone_id}`;
    varDefs.push("$milestoneId: MilestoneID");
    inputParts.push("milestoneWidget: { milestoneId: $milestoneId }");
    variables.milestoneId = milestoneGID;
  }

  if (options.iteration_id !== undefined) {
    const iterationGID = options.iteration_id.startsWith("gid://")
      ? options.iteration_id
      : `gid://gitlab/Iteration/${options.iteration_id}`;
    varDefs.push("$iterationId: IterationID");
    inputParts.push("iterationWidget: { iterationId: $iterationId }");
    variables.iterationId = iterationGID;
  }

  if (options.confidential !== undefined) {
    varDefs.push("$confidential: Boolean");
    inputParts.push("confidential: $confidential");
    variables.confidential = options.confidential;
  }

  // Custom fields widget
  if (options.custom_fields && options.custom_fields.length > 0) {
    const cfValues = options.custom_fields.map(cf => {
      const cfId = cf.custom_field_id.startsWith("gid://")
        ? cf.custom_field_id
        : `gid://gitlab/IssuablesCustomField/${cf.custom_field_id}`;
      const val: any = { customFieldId: cfId };
      if (cf.text_value !== undefined) val.textValue = cf.text_value;
      if (cf.number_value !== undefined) val.numberValue = cf.number_value;
      if (cf.selected_option_ids !== undefined) val.selectedOptionIds = cf.selected_option_ids;
      if (cf.date_value !== undefined) val.dateValue = cf.date_value;
      return val;
    });
    varDefs.push("$customFieldsWidget: [WorkItemWidgetCustomFieldValueInputType!]");
    inputParts.push("customFieldsWidget: $customFieldsWidget");
    variables.customFieldsWidget = cfValues;
  }

  // Hierarchy: set parent or remove parent
  if (options.remove_parent) {
    inputParts.push("hierarchyWidget: { parentId: null }");
  } else if (options.parent_iid !== undefined) {
    const parentProjectId = options.parent_project_id || projectId;
    const { workItemGID: parentGID } = await resolveWorkItemGID(parentProjectId, options.parent_iid);
    varDefs.push("$parentId: WorkItemID");
    inputParts.push("hierarchyWidget: { parentId: $parentId }");
    variables.parentId = parentGID;
  }

  // Execute the main update mutation
  const mutation = `mutation(${varDefs.join(", ")}) {
    workItemUpdate(input: { ${inputParts.join(", ")} }) {
      workItem {
        id
        iid
        title
        state
        webUrl
        workItemType { name }
        widgets {
          __typename
          ... on WorkItemWidgetStatus { status { id name category color } }
          ... on WorkItemWidgetLabels { labels { nodes { title } } }
          ... on WorkItemWidgetAssignees { assignees { nodes { username } } }
          ... on WorkItemWidgetWeight { weight }
          ... on WorkItemWidgetHierarchy {
            parent { id title workItemType { name } }
          }
          ... on WorkItemWidgetHealthStatus { healthStatus }
          ... on WorkItemWidgetStartAndDueDate { startDate dueDate }
          ... on WorkItemWidgetMilestone { milestone { id title } }
        }
      }
      errors
    }
  }`;

  const data = await executeGraphQL<{
    workItemUpdate: { workItem: any; errors: string[] };
  }>(mutation, variables);

  if (data.workItemUpdate.errors?.length > 0) {
    throw new Error(`Failed to update work item: ${data.workItemUpdate.errors.join(", ")}`);
  }

  // Handle children_to_add: use separate workItemUpdate call with hierarchyWidget.childrenIds
  if (options.children_to_add && options.children_to_add.length > 0) {
    const childGIDs: string[] = [];
    for (const child of options.children_to_add) {
      const { workItemGID: childGID } = await resolveWorkItemGID(child.project_id || projectId, child.iid);
      childGIDs.push(childGID);
    }
    const addData = await executeGraphQL<{
      workItemUpdate: { errors: string[] };
    }>(
      `mutation($id: WorkItemID!, $childrenIds: [WorkItemID!]!) {
        workItemUpdate(input: { id: $id, hierarchyWidget: { childrenIds: $childrenIds } }) {
          errors
        }
      }`,
      { id: workItemGID, childrenIds: childGIDs }
    );
    if (addData.workItemUpdate.errors?.length > 0) {
      throw new Error(`Failed to add children: ${addData.workItemUpdate.errors.join(", ")}`);
    }
  }

  // Handle children_to_remove: remove parent from each child
  if (options.children_to_remove && options.children_to_remove.length > 0) {
    for (const child of options.children_to_remove) {
      await removeIssueParent(child.project_id || projectId, child.iid);
    }
  }

  // Handle linked_items_to_add: use workItemAddLinkedItems mutation
  if (options.linked_items_to_add && options.linked_items_to_add.length > 0) {
    // Group by link_type since each mutation call needs a single linkType
    const groupedByType: Record<string, string[]> = {};
    for (const item of options.linked_items_to_add) {
      const linkType = item.link_type || "RELATED";
      if (!groupedByType[linkType]) groupedByType[linkType] = [];
      const { workItemGID: targetGID } = await resolveWorkItemGID(item.project_id || projectId, item.iid);
      groupedByType[linkType].push(targetGID);
    }
    for (const [linkType, targetGIDs] of Object.entries(groupedByType)) {
      const addLinkedData = await executeGraphQL<{
        workItemAddLinkedItems: { errors: string[] };
      }>(
        `mutation($id: WorkItemID!, $workItemsIds: [WorkItemID!]!, $linkType: WorkItemRelatedLinkType!) {
          workItemAddLinkedItems(input: { id: $id, workItemsIds: $workItemsIds, linkType: $linkType }) {
            errors
          }
        }`,
        { id: workItemGID, workItemsIds: targetGIDs, linkType }
      );
      if (addLinkedData.workItemAddLinkedItems.errors?.length > 0) {
        throw new Error(`Failed to add linked items: ${addLinkedData.workItemAddLinkedItems.errors.join(", ")}`);
      }
    }
  }

  // Handle linked_items_to_remove: use workItemRemoveLinkedItems mutation
  if (options.linked_items_to_remove && options.linked_items_to_remove.length > 0) {
    const targetGIDs: string[] = [];
    for (const item of options.linked_items_to_remove) {
      const { workItemGID: targetGID } = await resolveWorkItemGID(item.project_id || projectId, item.iid);
      targetGIDs.push(targetGID);
    }
    const removeLinkedData = await executeGraphQL<{
      workItemRemoveLinkedItems: { errors: string[] };
    }>(
      `mutation($id: WorkItemID!, $workItemsIds: [WorkItemID!]!) {
        workItemRemoveLinkedItems(input: { id: $id, workItemsIds: $workItemsIds }) {
          errors
        }
      }`,
      { id: workItemGID, workItemsIds: targetGIDs }
    );
    if (removeLinkedData.workItemRemoveLinkedItems.errors?.length > 0) {
      throw new Error(`Failed to remove linked items: ${removeLinkedData.workItemRemoveLinkedItems.errors.join(", ")}`);
    }
  }

  // Handle incident-specific fields via separate mutations
  if (options.severity !== undefined) {
    await updateIncidentSeverity(projectPath, iid, options.severity);
  }
  if (options.escalation_status !== undefined) {
    await updateIncidentEscalationStatus(projectPath, iid, options.escalation_status);
  }

  // Flatten the response
  const wi = data.workItemUpdate.workItem;
  const widgets = wi?.widgets || [];
  const statusW = widgets.find((w: any) => w.__typename === "WorkItemWidgetStatus");
  const labelsW = widgets.find((w: any) => w.__typename === "WorkItemWidgetLabels");
  const assigneesW = widgets.find((w: any) => w.__typename === "WorkItemWidgetAssignees");
  const weightW = widgets.find((w: any) => w.__typename === "WorkItemWidgetWeight");
  const hierarchyW = widgets.find((w: any) => w.__typename === "WorkItemWidgetHierarchy");
  const healthStatusW = widgets.find((w: any) => w.__typename === "WorkItemWidgetHealthStatus");
  const datesW = widgets.find((w: any) => w.__typename === "WorkItemWidgetStartAndDueDate");
  const milestoneW = widgets.find((w: any) => w.__typename === "WorkItemWidgetMilestone");

  return {
    id: wi.id,
    iid: wi.iid,
    title: wi.title,
    state: wi.state,
    type: wi.workItemType?.name,
    webUrl: wi.webUrl,
    status: statusW?.status || null,
    labels: (labelsW?.labels?.nodes || []).map((l: any) => l.title),
    assignees: (assigneesW?.assignees?.nodes || []).map((a: any) => a.username),
    weight: weightW?.weight ?? null,
    parent: hierarchyW?.parent || null,
    healthStatus: healthStatusW?.healthStatus || null,
    startDate: datesW?.startDate || null,
    dueDate: datesW?.dueDate || null,
    milestone: milestoneW?.milestone || null,
    children_added: options.children_to_add?.length || 0,
    children_removed: options.children_to_remove?.length || 0,
    linked_items_added: options.linked_items_to_add?.length || 0,
    linked_items_removed: options.linked_items_to_remove?.length || 0,
    ...(options.severity !== undefined && { severity: options.severity }),
    ...(options.escalation_status !== undefined && { escalation_status: options.escalation_status }),
  };
}

/**
 * List all issue links for a specific issue
 * 이슈 관계 목록 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @returns {Promise<GitLabIssueWithLinkDetails[]>} List of issues with link details
 */
async function listIssueLinks(
  projectId: string,
  issueIid: number | string
): Promise<GitLabIssueWithLinkDetails[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}/links`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabIssueWithLinkDetailsSchema).parse(data);
}

/**
 * Get a specific issue link
 * 특정 이슈 관계 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @param {number} issueLinkId - The ID of the issue link
 * @returns {Promise<GitLabIssueLink>} The issue link
 */
async function getIssueLink(
  projectId: string,
  issueIid: number | string,
  issueLinkId: number | string
): Promise<GitLabIssueLink> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/issues/${issueIid}/links/${issueLinkId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabIssueLinkSchema.parse(data);
}

/**
 * Create an issue link between two issues
 * 이슈 관계 생성
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @param {string} targetProjectId - The ID or URL-encoded path of the target project
 * @param {number} targetIssueIid - The internal ID of the target project issue
 * @param {string} linkType - The type of the relation (relates_to, blocks, is_blocked_by)
 * @returns {Promise<GitLabIssueLink>} The created issue link
 */
async function createIssueLink(
  projectId: string,
  issueIid: number | string,
  targetProjectId: string,
  targetIssueIid: number | string,
  linkType: "relates_to" | "blocks" | "is_blocked_by" = "relates_to"
): Promise<GitLabIssueLink> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  targetProjectId = decodeURIComponent(targetProjectId); // Decode target project ID as well
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}/links`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({
      target_project_id: targetProjectId,
      target_issue_iid: targetIssueIid,
      link_type: linkType,
    }),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabIssueLinkSchema.parse(data);
}

/**
 * Delete an issue link
 * 이슈 관계 삭제
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @param {number} issueLinkId - The ID of the issue link
 * @returns {Promise<void>}
 */
async function deleteIssueLink(
  projectId: string,
  issueIid: number | string,
  issueLinkId: number | string
): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/issues/${issueIid}/links/${issueLinkId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });

  await handleGitLabError(response);
}

/**
 * Create a new merge request in a GitLab project
 * 병합 요청 생성
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {z.infer<typeof CreateMergeRequestOptionsSchema>} options - Merge request creation options
 * @returns {Promise<GitLabMergeRequest>} The created merge request
 */
async function createMergeRequest(
  projectId: string,
  options: z.infer<typeof CreateMergeRequestOptionsSchema>
): Promise<GitLabMergeRequest> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({
      title: options.title,
      description: options.description,
      source_branch: options.source_branch,
      target_branch: options.target_branch,
      target_project_id: options.target_project_id,
      assignee_ids: options.assignee_ids,
      reviewer_ids: options.reviewer_ids,
      labels: options.labels?.join(","),
      allow_collaboration: options.allow_collaboration,
      draft: options.draft,
      remove_source_branch: options.remove_source_branch,
      squash: options.squash,
    }),
  });

  if (response.status === 400) {
    const errorBody = await response.text();
    throw new Error(`Invalid request: ${errorBody}`);
  }

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const data = await response.json();
  return GitLabMergeRequestSchema.parse(data);
}

/**
 * Shared helper function for listing discussions
 * 토론 목록 조회를 위한 공유 헬퍼 함수
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {"issues" | "merge_requests"} resourceType - The type of resource (issues or merge_requests)
 * @param {number} resourceIid - The IID of the issue or merge request
 * @param {PaginationOptions} options - Pagination and sorting options
 * @returns {Promise<PaginatedDiscussionsResponse>} Paginated list of discussions
 */
async function listDiscussions(
  projectId: string,
  resourceType: "issues" | "merge_requests",
  resourceIid: number | string,
  options: PaginationOptions = {}
): Promise<PaginatedDiscussionsResponse> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/${resourceType}/${resourceIid}/discussions`
  );

  // Add query parameters for pagination and sorting
  if (options.page) {
    url.searchParams.append("page", options.page.toString());
  }
  if (options.per_page) {
    url.searchParams.append("per_page", options.per_page.toString());
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const discussions = await response.json();

  // Extract pagination headers
  const pagination = {
    x_next_page: response.headers.get("x-next-page")
      ? Number.parseInt(response.headers.get("x-next-page")!, 10)
      : null,
    x_page: response.headers.get("x-page")
      ? Number.parseInt(response.headers.get("x-page")!, 10)
      : undefined,
    x_per_page: response.headers.get("x-per-page")
      ? Number.parseInt(response.headers.get("x-per-page")!, 10)
      : undefined,
    x_prev_page: response.headers.get("x-prev-page")
      ? Number.parseInt(response.headers.get("x-prev-page")!, 10)
      : null,
    x_total: response.headers.get("x-total")
      ? Number.parseInt(response.headers.get("x-total")!, 10)
      : null,
    x_total_pages: response.headers.get("x-total-pages")
      ? Number.parseInt(response.headers.get("x-total-pages")!, 10)
      : null,
  };

  return PaginatedDiscussionsResponseSchema.parse({
    items: discussions,
    pagination: pagination,
  });
}

/**
 * List merge request discussion items
 * 병합 요청 토론 목록 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The IID of a merge request
 * @param {DiscussionPaginationOptions} options - Pagination and sorting options
 * @returns {Promise<GitLabDiscussion[]>} List of discussions
 */
async function listMergeRequestDiscussions(
  projectId: string,
  mergeRequestIid: number | string,
  options: PaginationOptions = {}
): Promise<PaginatedDiscussionsResponse> {
  return listDiscussions(projectId, "merge_requests", mergeRequestIid, options);
}

/**
 * List discussions for an issue
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The internal ID of the project issue
 * @param {DiscussionPaginationOptions} options - Pagination and sorting options
 * @returns {Promise<GitLabDiscussion[]>} List of issue discussions
 */
async function listIssueDiscussions(
  projectId: string,
  issueIid: number | string,
  options: PaginationOptions = {}
): Promise<PaginatedDiscussionsResponse> {
  return listDiscussions(projectId, "issues", issueIid, options);
}

async function deleteMergeRequestDiscussionNote(
  projectId: string,
  mergeRequestIid: number | string,
  discussionId: string,
  noteId: number | string
): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/discussions/${discussionId}/notes/${noteId}`
  );
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }
}

/**
 * Modify an existing merge request thread note
 * 병합 요청 토론 노트 수정
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The IID of a merge request
 * @param {string} discussionId - The ID of a thread
 * @param {number} noteId - The ID of a thread note
 * @param {string} body - The new content of the note
 * @param {boolean} [resolved] - Resolve/unresolve state
 * @returns {Promise<GitLabDiscussionNote>} The updated note
 */
async function updateMergeRequestDiscussionNote(
  projectId: string,
  mergeRequestIid: number | string,
  discussionId: string,
  noteId: number | string,
  body?: string,
  resolved?: boolean
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/discussions/${discussionId}/notes/${noteId}`
  );

  // Only one of body or resolved can be sent according to GitLab API
  const payload: { body?: string; resolved?: boolean } = {};
  if (body !== undefined) {
    payload.body = body;
  } else if (resolved !== undefined) {
    payload.resolved = resolved;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

/**
 * Update an issue discussion note
 *
 * Note: Only one of `body` or `resolved` can be provided per GitLab API requirements.
 * At least one parameter must be provided.
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} issueIid - The IID of an issue
 * @param {string} discussionId - The ID of a thread
 * @param {number|string} noteId - The ID of a thread note
 * @param {string} [body] - The new content of the note (optional, mutually exclusive with resolved)
 * @param {boolean} [resolved] - Resolve (true) or unresolve (false) the thread (optional, mutually exclusive with body)
 * @returns {Promise<GitLabDiscussionNote>} The updated note
 *
 * @example
 * // Resolve a thread
 * await updateIssueNote('mygroup/myproject', 123, 'abc123', 456, undefined, true);
 *
 * @example
 * // Unresolve a thread
 * await updateIssueNote('mygroup/myproject', 123, 'abc123', 456, undefined, false);
 *
 * @example
 * // Update note body
 * await updateIssueNote('mygroup/myproject', 123, 'abc123', 456, 'Updated content');
 */
async function updateIssueNote(
  projectId: string,
  issueIid: number | string,
  discussionId: string,
  noteId: number | string,
  body?: string,
  resolved?: boolean
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/issues/${issueIid}/discussions/${discussionId}/notes/${noteId}`
  );

  // Only one of body or resolved can be sent according to GitLab API
  const payload: { body?: string; resolved?: boolean } = {};
  if (body !== undefined) {
    payload.body = body;
  } else if (resolved !== undefined) {
    payload.resolved = resolved;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

/**
 * Create a note in an issue discussion
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} issueIid - The IID of an issue
 * @param {string} [discussionId] - The ID of a thread (omit for top-level note)
 * @param {string} body - The content of the new note
 * @param {string} [createdAt] - The creation date of the note (ISO 8601 format)
 * @returns {Promise<GitLabDiscussionNote>} The created note
 */
async function createIssueNote(
  projectId: string,
  issueIid: number | string,
  discussionId: string | undefined,
  body: string,
  createdAt?: string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const basePath = `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
    getEffectiveProjectId(projectId)
  )}/issues/${issueIid}`;
  const url = new URL(
    discussionId
      ? `${basePath}/discussions/${discussionId}/notes`
      : `${basePath}/notes`
  );

  const payload: { body: string; created_at?: string } = { body };
  if (createdAt) {
    payload.created_at = createdAt;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

/**
 * Add a new discussion note to an existing merge request thread
 * 기존 병합 요청 스레드에 새 노트 추가
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The IID of a merge request
 * @param {string} discussionId - The ID of a thread
 * @param {string} body - The content of the new note
 * @param {string} [createdAt] - The creation date of the note (ISO 8601 format)
 * @returns {Promise<GitLabDiscussionNote>} The created note
 */
async function createMergeRequestDiscussionNote(
  projectId: string,
  mergeRequestIid: number | string,
  discussionId: string,
  body: string,
  createdAt?: string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/discussions/${discussionId}/notes`
  );

  const payload: { body: string; created_at?: string } = { body };
  if (createdAt) {
    payload.created_at = createdAt;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

async function createMergeRequestNote(
  projectId: string,
  mergeRequestIid: number | string,
  body: string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/notes`
  );

  const payload = {
    id: projectId,
    merge_request_iid: mergeRequestIid,
    body,
  };

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

async function deleteMergeRequestNote(
  projectId: string,
  mergeRequestIid: string,
  noteId: string
): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/notes/${noteId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }
}

async function getMergeRequestNote(
  projectId: string,
  mergeRequestIid: string,
  noteId: string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/notes/${noteId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

async function getMergeRequestNotes(
  projectId: string,
  mergeRequestIid: string,
  sort?: "asc" | "desc",
  order_by?: "created_at" | "updated_at",
  per_page?: number,
  page?: number
): Promise<GitLabDiscussionNote[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/notes`
  );

  if (sort) {
    url.searchParams.append("sort", sort);
  }

  if (order_by) {
    url.searchParams.append("order_by", order_by);
  }

  if (per_page) {
    url.searchParams.append("per_page", per_page.toString());
  }

  if (page) {
    url.searchParams.append("page", page.toString());
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabDiscussionNoteSchema).parse(data);
}

async function updateMergeRequestNote(
  projectId: string,
  mergeRequestIid: string,
  noteId: string,
  body: string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/notes/${noteId}`
  );

  const payload = {
    id: projectId,
    merge_request_iid: mergeRequestIid,
    note_id: noteId,
    body,
  };

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionNoteSchema.parse(data);
}

function encodeRepoFilePayloadContent(content: string): string {
  if (GITLAB_REPO_FILE_ENCODING === "base64") {
    return Buffer.from(content).toString("base64");
  }
  return content;
}

/**
 * Create or update a file in a GitLab project
 * 파일 생성 또는 업데이트
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} filePath - The path of the file to create or update
 * @param {string} content - The content of the file
 * @param {string} commitMessage - The commit message
 * @param {string} branch - The branch name
 * @param {string} [previousPath] - The previous path of the file in case of rename
 * @returns {Promise<GitLabCreateUpdateFileResponse>} The file update response
 */
async function createOrUpdateFile(
  projectId: string,
  filePath: string,
  content: string,
  commitMessage: string,
  branch: string,
  previousPath?: string,
  last_commit_id?: string,
  commit_id?: string
): Promise<GitLabCreateUpdateFileResponse> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const encodedPath = encodeURIComponent(filePath);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/files/${encodedPath}`
  );

  const body: Record<string, any> = {
    branch,
    content: encodeRepoFilePayloadContent(content),
    commit_message: commitMessage,
    encoding: GITLAB_REPO_FILE_ENCODING,
    ...(previousPath ? { previous_path: previousPath } : {}),
  };

  // Check if file exists
  let method = "POST";
  try {
    // Get file contents to check existence and retrieve commit IDs
    const fileData = await getFileContents(projectId, filePath, branch);
    method = "PUT";

    // If fileData is not an array, it's a file content object with commit IDs
    if (!Array.isArray(fileData)) {
      // Use commit IDs from the file data if not provided in parameters
      if (!commit_id && fileData.commit_id) {
        body.commit_id = fileData.commit_id;
      } else if (commit_id) {
        body.commit_id = commit_id;
      }

      if (!last_commit_id && fileData.last_commit_id) {
        body.last_commit_id = fileData.last_commit_id;
      } else if (last_commit_id) {
        body.last_commit_id = last_commit_id;
      }
    }
  } catch (error) {
    if (!(error instanceof Error && error.message.includes("File not found"))) {
      throw error;
    }
    // File doesn't exist, use POST - no need for commit IDs for new files
    // But still use any provided as parameters if they exist
    if (commit_id) {
      body.commit_id = commit_id;
    }
    if (last_commit_id) {
      body.last_commit_id = last_commit_id;
    }
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method,
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const data = await response.json();
  return GitLabCreateUpdateFileResponseSchema.parse(data);
}

/**
 * Create a commit in a GitLab project repository
 * 저장소에 커밋 생성
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} message - The commit message
 * @param {string} branch - The branch name
 * @param {FileOperation[]} actions - Array of file operations for the commit
 * @returns {Promise<GitLabCommit>} The created commit
 */
async function createCommit(
  projectId: string,
  message: string,
  branch: string,
  actions: FileOperation[]
): Promise<GitLabCommit> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/commits`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({
      branch,
      commit_message: message,
      actions: actions.map(action => ({
        action: "create",
        file_path: action.path,
        content: encodeRepoFilePayloadContent(action.content),
        encoding: GITLAB_REPO_FILE_ENCODING,
      })),
    }),
  });

  if (response.status === 400) {
    const errorBody = await response.text();
    throw new Error(`Invalid request: ${errorBody}`);
  }

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const data = await response.json();
  return GitLabCommitSchema.parse(data);
}

/**
 * Search for GitLab projects
 * 프로젝트 검색
 *
 * @param {string} query - The search query
 * @param {number} [page=1] - The page number
 * @param {number} [perPage=20] - Number of items per page
 * @returns {Promise<GitLabSearchResponse>} The search results
 */
async function searchProjects(
  query: string,
  page: number = 1,
  perPage: number = 20
): Promise<GitLabSearchResponse> {
  const url = new URL(`${getEffectiveApiUrl()}/projects`);
  url.searchParams.append("search", query);
  url.searchParams.append("page", page.toString());
  url.searchParams.append("per_page", perPage.toString());
  url.searchParams.append("order_by", "id");
  url.searchParams.append("sort", "desc");

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const projects = (await response.json()) as GitLabRepository[];
  const totalCount = response.headers.get("x-total");
  const totalPages = response.headers.get("x-total-pages");

  // GitLab API doesn't return these headers for results > 10,000
  const count = totalCount ? Number.parseInt(totalCount, 10) : projects.length;

  return GitLabSearchResponseSchema.parse({
    count,
    total_pages: totalPages ? Number.parseInt(totalPages, 10) : Math.ceil(count / perPage),
    current_page: page,
    items: projects,
  });
}

/**
 * Search for code blobs using GitLab Search API
 * Supports global, project-level, and group-level search
 */
async function searchBlobs(params: {
  search: string;
  project_id?: string;
  group_id?: string;
  ref?: string;
  filename?: string;
  path?: string;
  extension?: string;
  page?: number;
  per_page?: number;
}): Promise<GitLabSearchBlobResult[]> {
  let basePath: string;
  if (params.project_id) {
    const decodedProjectId = decodeURIComponent(params.project_id);
    const projectId = encodeURIComponent(getEffectiveProjectId(decodedProjectId));
    basePath = `${getEffectiveApiUrl()}/projects/${projectId}/search`;
  } else if (params.group_id) {
    const groupId = encodeURIComponent(decodeURIComponent(params.group_id));
    basePath = `${getEffectiveApiUrl()}/groups/${groupId}/search`;
  } else {
    basePath = `${getEffectiveApiUrl()}/search`;
  }

  const url = new URL(basePath);
  url.searchParams.append("scope", "blobs");
  url.searchParams.append("search", params.search);

  if (params.ref) {
    url.searchParams.append("ref", params.ref);
  }
  if (params.page) {
    url.searchParams.append("page", params.page.toString());
  }
  if (params.per_page) {
    url.searchParams.append("per_page", params.per_page.toString());
  }

  if (params.filename) {
    url.searchParams.append("filename", params.filename);
  }
  if (params.path) {
    url.searchParams.append("path", params.path);
  }
  if (params.extension) {
    url.searchParams.append("extension", params.extension);
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();
  return z.array(GitLabSearchBlobResultSchema).parse(data);
}

/**
 * Create a new GitLab repository
 * 새 저장소 생성
 *
 * @param {z.infer<typeof CreateRepositoryOptionsSchema>} options - Repository creation options
 * @returns {Promise<GitLabRepository>} The created repository
 */
async function createRepository(
  options: z.infer<typeof CreateRepositoryOptionsSchema>
): Promise<GitLabRepository> {
  const response = await fetch(`${getEffectiveApiUrl()}/projects`, {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({
      name: options.name,
      description: options.description,
      visibility: options.visibility,
      initialize_with_readme: options.initialize_with_readme,
      default_branch: "main",
      path: options.name.toLowerCase().replaceAll(/\s+/g, "-"),
    }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const data = await response.json();
  return GitLabRepositorySchema.parse(data);
}

/**
 * Get merge request details
 * MR 조회 함수 (Function to retrieve merge request)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request (Optional)
 * @param {string} [branchName] - The name of the branch to search for merge request by branch name (Optional)
 * @returns {Promise<GitLabMergeRequest>} The merge request details
 */
async function getMergeRequest(
  projectId: string,
  mergeRequestIid?: number | string,
  branchName?: string
): Promise<GitLabMergeRequest> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  let url: URL;

  if (mergeRequestIid) {
    url = new URL(
      `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
        getEffectiveProjectId(projectId)
      )}/merge_requests/${mergeRequestIid}`
    );
    url.searchParams.append("include_diverged_commits_count", "true");
  } else if (branchName) {
    url = new URL(
      `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
        getEffectiveProjectId(projectId)
      )}/merge_requests?source_branch=${encodeURIComponent(branchName)}`
    );
  } else {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();

  // If response is an array (Comes from branchName search), return the first item if exist
  if (Array.isArray(data) && data.length > 0) {
    const mergeRequest = GitLabMergeRequestSchema.parse(data[0]);
    return getMergeRequest(projectId, mergeRequest.iid, undefined);
  }

  return GitLabMergeRequestSchema.parse(data);
}

async function getMergeRequestSourceCommitCount(
  projectId: string,
  mergeRequestIid: string
): Promise<number> {
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/commits`
  );
  url.searchParams.append("per_page", "100");

  let totalCount = 0;
  let page = 1;

  while (true) {
    url.searchParams.set("page", String(page));
    const response = await fetch(url.toString(), {
      ...getFetchConfig(),
    });
    await handleGitLabError(response);

    const data = await response.json();
    if (!Array.isArray(data)) {
      throw new Error("Unexpected merge request commits response format");
    }

    totalCount += data.length;

    const nextPage = response.headers.get("x-next-page");
    if (!nextPage) {
      break;
    }

    page = Number.parseInt(nextPage, 10);
    if (Number.isNaN(page) || page <= 0) {
      break;
    }
  }

  return totalCount;
}

async function getProjectMergeMethod(projectId: string): Promise<string | null> {
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}`
  );
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);

  const data: unknown = await response.json();
  const mergeMethod = z
    .object({
      merge_method: z.string().nullable().optional(),
    })
    .parse(data).merge_method;

  return typeof mergeMethod === "string" ? mergeMethod : null;
}



async function buildMergeRequestCommitAdditionSummary(
  projectId: string,
  mergeRequest: GitLabMergeRequest
): Promise<GitLabMergeRequestWithDeploymentSummary["commit_addition_summary"]> {
  try {
    const sourceCommitCount = await getMergeRequestSourceCommitCount(projectId, mergeRequest.iid);
    const mergeMethod = await getProjectMergeMethod(projectId);
    const mergeCommitCount = estimateMergeCommitCount(mergeMethod, sourceCommitCount);

    const summary =
      mergeCommitCount === null
        ? null
        : `${sourceCommitCount} commits and ${mergeCommitCount} merge commit${mergeCommitCount === 1 ? "" : "s"} will be added to ${mergeRequest.target_branch}.`;

    return {
      target_branch: mergeRequest.target_branch,
      source_commits_count: sourceCommitCount,
      merge_method: mergeMethod,
      merge_commit_count: mergeCommitCount,
      summary,
    };
  } catch (error) {
    const unavailableReason = error instanceof Error ? error.message : String(error);
    return {
      target_branch: mergeRequest.target_branch,
      source_commits_count: null,
      merge_method: null,
      merge_commit_count: null,
      summary: null,
      unavailable_reason: unavailableReason,
    };
  }
}

async function buildMergeRequestApprovalSummary(
  projectId: string,
  mergeRequestIid: string
): Promise<GitLabMergeRequestWithDeploymentSummary["approval_summary"]> {
  try {
    const approvalState = await getMergeRequestApprovalState(projectId, mergeRequestIid);
    const approvedByUsers = approvalState.approved_by || [];
    const approvedByUsernames =
      approvalState.approved_by_usernames || approvedByUsers.map(user => user.username);
    const inferredApproved = inferMergeRequestApproved(approvalState.rules);

    return {
      approved: approvalState.approved ?? inferredApproved,
      user_has_approved: approvalState.user_has_approved ?? null,
      user_can_approve: approvalState.user_can_approve ?? null,
      approved_by: approvedByUsers,
      approved_by_usernames: approvedByUsernames,
      rules_count: approvalState.rules?.length ?? null,
      source_endpoint: approvalState.source_endpoint ?? null,
    };
  } catch (error) {
    const unavailableReason = error instanceof Error ? error.message : String(error);
    return {
      approved: null,
      user_has_approved: null,
      user_can_approve: null,
      approved_by: [],
      approved_by_usernames: [],
      rules_count: null,
      source_endpoint: null,
      unavailable_reason: unavailableReason,
    };
  }
}

function toMergeRequestDeploymentSummaryRecord(
  deployment: GitLabDeployment
): GitLabMergeRequestDeploymentSummaryRecord {
  return {
    id: deployment.id,
    status: deployment.status,
    ref: deployment.ref,
    sha: deployment.sha,
    created_at: deployment.created_at,
    updated_at: deployment.updated_at,
    finished_at: deployment.finished_at,
    web_url: deployment.web_url,
    environment: deployment.environment
      ? {
          id: deployment.environment.id,
          name: deployment.environment.name,
          slug: deployment.environment.slug,
          external_url: deployment.environment.external_url,
          state: deployment.environment.state,
          tier: deployment.environment.tier,
        }
      : undefined,
    deployable:
      deployment.deployable === null
        ? null
        : deployment.deployable
          ? {
              id: deployment.deployable.id,
              name: deployment.deployable.name,
              status: deployment.deployable.status,
              stage: deployment.deployable.stage,
              web_url: deployment.deployable.web_url,
              pipeline: deployment.deployable.pipeline
                ? {
                    id: deployment.deployable.pipeline.id,
                    status: deployment.deployable.pipeline.status,
                    ref: deployment.deployable.pipeline.ref,
                    sha: deployment.deployable.pipeline.sha,
                    web_url: deployment.deployable.pipeline.web_url,
                  }
                : undefined,
            }
          : undefined,
  };
}

function sortDeploymentsByCreatedAtDesc(deployments: GitLabDeployment[]): GitLabDeployment[] {
  return [...deployments].sort((a, b) => {
    const aTime = Date.parse(a.created_at);
    const bTime = Date.parse(b.created_at);

    if (Number.isNaN(aTime) || Number.isNaN(bTime)) {
      return b.created_at.localeCompare(a.created_at);
    }

    return bTime - aTime;
  });
}

async function buildMergeRequestDeploymentSummary(
  projectId: string,
  mergeRequest: GitLabMergeRequest
): Promise<GitLabMergeRequestWithDeploymentSummary["deployment_summary"]> {
  const lookupSha = mergeRequest.merge_commit_sha ?? mergeRequest.diff_refs?.head_sha ?? null;

  if (!lookupSha) {
    return {
      lookup_sha: null,
      sort: "created_at_desc",
      limit: MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT,
      total_count: 0,
      returned_count: 0,
      records: [],
    };
  }

  try {
    const deployments = await listDeployments(projectId, {
      sha: lookupSha,
      order_by: "created_at",
      sort: "desc",
      per_page: 100,
    });
    const sortedDeployments = sortDeploymentsByCreatedAtDesc(deployments);
    const records = sortedDeployments
      .slice(0, MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT)
      .map(toMergeRequestDeploymentSummaryRecord);

    return {
      lookup_sha: lookupSha,
      sort: "created_at_desc",
      limit: MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT,
      total_count: sortedDeployments.length,
      returned_count: records.length,
      records,
    };
  } catch (error) {
    const unavailableReason = error instanceof Error ? error.message : String(error);

    return {
      lookup_sha: lookupSha,
      sort: "created_at_desc",
      limit: MERGE_REQUEST_DEPLOYMENT_SUMMARY_LIMIT,
      total_count: 0,
      returned_count: 0,
      records: [],
      unavailable_reason: unavailableReason,
    };
  }
}

/**
 * Get merge request changes/diffs
 * MR 변경사항 조회 함수 (Function to retrieve merge request changes)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request (Either mergeRequestIid or branchName must be provided)
 * @param {string} [branchName] - The name of the branch to search for merge request by branch name (Either mergeRequestIid or branchName must be provided)
 * @param {string} [view] - The view type for the diff (inline or parallel)
 * @returns {Promise<GitLabMergeRequestDiff[]>} The merge request diffs
 */
async function getMergeRequestDiffs(
  projectId: string,
  mergeRequestIid?: number | string,
  branchName?: string,
  view?: "inline" | "parallel"
): Promise<GitLabMergeRequestDiff[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  if (!mergeRequestIid && !branchName) {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  if (branchName && !mergeRequestIid) {
    const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
    mergeRequestIid = mergeRequest.iid;
  }

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/changes`
  );

  if (view) {
    url.searchParams.append("view", view);
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = (await response.json()) as { changes: unknown };
  return z.array(GitLabDiffSchema).parse(data.changes);
}

/**
 * Get merge request changes with detailed information including commits, diff_refs, and more
 * 마지막으로 추가된 상세한 MR 변경사항 조회 함수 (Detailed merge request changes retrieval function)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request (Either mergeRequestIid or branchName must be provided)
 * @param {string} [branchName] - The name of the branch to search for merge request by branch name (Either mergeRequestIid or branchName must be provided)
 * @param {boolean} [unidiff] - Return diff in unidiff format
 * @returns {Promise<any>} The complete merge request changes response
 */
async function listMergeRequestDiffs(
  projectId: string,
  mergeRequestIid?: number | string,
  branchName?: string,
  page?: number,
  perPage?: number,
  unidiff?: boolean
): Promise<any> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  if (!mergeRequestIid && !branchName) {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  if (branchName && !mergeRequestIid) {
    const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
    mergeRequestIid = mergeRequest.iid;
  }

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/diffs`
  );

  if (page) {
    url.searchParams.append("page", page.toString());
  }

  if (perPage) {
    url.searchParams.append("per_page", perPage.toString());
  }

  if (unidiff) {
    url.searchParams.append("unidiff", "true");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  return await response.json(); // Return full response including commits, diff_refs, changes, etc.
}

/**
 * Returns the list of changed files in a merge request WITHOUT diff content.
 * Use this as STEP 1 of code review: get file paths, then fetch diffs in batches
 * with getMergeRequestFileDiff to avoid loading the entire diff payload at once.
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} [mergeRequestIid] - The internal ID of the merge request
 * @param {string} [branchName] - The name of the source branch (used to resolve MR if iid not provided)
 * @param {string[]} [excludedFilePatterns] - Regex patterns to exclude files from the result
 * @returns {Promise<any[]>} Array of changed file metadata (new_path, old_path, new_file, deleted_file, renamed_file)
 */
async function listMergeRequestChangedFiles(
  projectId: string,
  mergeRequestIid?: number | string,
  branchName?: string,
  excludedFilePatterns?: string[]
): Promise<any[]> {
  projectId = decodeURIComponent(projectId);
  if (!mergeRequestIid && !branchName) {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  if (branchName && !mergeRequestIid) {
    const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
    mergeRequestIid = mergeRequest.iid;
  }

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/changes`
  );

  const response = await fetch(url.toString(), { ...getFetchConfig() });
  await handleGitLabError(response);
  const data = (await response.json()) as { changes: any[] };

  const rawFiles = (data.changes || []).map((f: any) => ({
    new_path: f.new_path,
    old_path: f.old_path,
    new_file: f.new_file,
    deleted_file: f.deleted_file,
    renamed_file: f.renamed_file,
  }));

  return filterDiffsByPatterns(rawFiles, excludedFilePatterns);
}

/**
 * Get diffs for specific files from a merge request.
 * Use this as STEP 2 of code review: pass file paths obtained from
 * listMergeRequestChangedFiles to fetch their diffs efficiently.
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string[]} filePaths - List of file paths to retrieve diffs for
 * @param {number|string} [mergeRequestIid] - The internal ID of the merge request
 * @param {string} [branchName] - The name of the source branch (used to resolve MR if iid not provided)
 * @param {boolean} [unidiff] - Return diff in unified diff format
 * @returns {Promise<any[]>} Array of diff objects for each requested file, or error objects for files not found
 */
async function getMergeRequestFileDiff(
  projectId: string,
  filePaths: string[],
  mergeRequestIid?: number | string,
  branchName?: string,
  unidiff?: boolean
): Promise<any[]> {
  projectId = decodeURIComponent(projectId);
  if (!mergeRequestIid && !branchName) {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  if (branchName && !mergeRequestIid) {
    const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
    mergeRequestIid = mergeRequest.iid;
  }

  // Paginate through /diffs once, collecting all requested files.
  // More efficient than N separate searches when fetching multiple files.
  const remaining = new Set(filePaths);
  const results: any[] = [];
  let page = 1;
  const perPage = 20;

  while (remaining.size > 0) {
    const url = new URL(
      `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
        getEffectiveProjectId(projectId)
      )}/merge_requests/${mergeRequestIid}/diffs`
    );
    url.searchParams.append("page", page.toString());
    url.searchParams.append("per_page", perPage.toString());
    if (unidiff) {
      url.searchParams.append("unidiff", "true");
    }

    const response = await fetch(url.toString(), { ...getFetchConfig() });
    await handleGitLabError(response);
    const items = (await response.json()) as any[];

    if (!Array.isArray(items) || items.length === 0) {
      break;
    }

    for (const item of items) {
      if (remaining.has(item.new_path) || remaining.has(item.old_path)) {
        results.push(item);
        remaining.delete(item.new_path);
        remaining.delete(item.old_path);
      }
    }

    if (items.length < perPage) {
      break;
    }

    page++;
  }

  for (const notFound of remaining) {
    results.push({
      error: `File not found in merge request diffs: ${notFound}`,
      hint: "Use list_merge_request_changed_files to verify the correct file paths.",
    });
  }

  return results;
}

/**
 * Get branch comparison diffs
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} from - The branch name or commit SHA to compare from
 * @param {string} to - The branch name or commit SHA to compare to
 * @param {boolean} [straight] - Comparison method: false for '...' (default), true for '--'
 * @returns {Promise<GitLabCompareResult>} Branch comparison results
 */
async function getBranchDiffs(
  projectId: string,
  from: string,
  to: string,
  straight?: boolean
): Promise<GitLabCompareResult> {
  projectId = decodeURIComponent(projectId); // Decode project ID

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/compare`
  );

  url.searchParams.append("from", from);
  url.searchParams.append("to", to);

  if (straight !== undefined) {
    url.searchParams.append("straight", straight.toString());
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
  }

  const data = await response.json();
  return GitLabCompareResultSchema.parse(data);
}

/**
 * Update a merge request
 * MR 업데이트 함수 (Function to update merge request)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request (Optional)
 * @param {string} branchName - The name of the branch to search for merge request by branch name (Optional)
 * @param {Object} options - The update options
 * @returns {Promise<GitLabMergeRequest>} The updated merge request
 */
async function updateMergeRequest(
  projectId: string,
  options: Omit<
    z.infer<typeof UpdateMergeRequestSchema>,
    "project_id" | "merge_request_iid" | "source_branch"
  >,
  mergeRequestIid?: number | string,
  branchName?: string
): Promise<GitLabMergeRequest> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  if (!mergeRequestIid && !branchName) {
    throw new Error("Either mergeRequestIid or branchName must be provided");
  }

  if (branchName && !mergeRequestIid) {
    const mergeRequest = await getMergeRequest(projectId, undefined, branchName);
    mergeRequestIid = mergeRequest.iid;
  }

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(options),
  });

  await handleGitLabError(response);
  return GitLabMergeRequestSchema.parse(await response.json());
}

/**
 * Merge a merge request
 * マージリクエストをマージする
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request
 * @param {Object} options - Options for merging the merge request
 * @returns {Promise<GitLabMergeRequest>} The merged merge request
 */
async function mergeMergeRequest(
  projectId: string,
  options: Omit<z.infer<typeof MergeMergeRequestSchema>, "project_id" | "merge_request_iid">,
  mergeRequestIid?: number | string
): Promise<GitLabMergeRequest> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/merge`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(options),
  });

  await handleGitLabError(response);
  return GitLabMergeRequestSchema.parse(await response.json());
}

/**
 * Approve a merge request
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string | number} mergeRequestIid - The internal ID of the merge request
 * @param {string} sha - Optional SHA to approve (for validation that MR hasn't changed)
 * @param {string} approvalPassword - Optional password for approvals requiring re-authentication
 * @returns {Promise<GitLabMergeRequestApprovalState>} The approval state after approving
 */
async function approveMergeRequest(
  projectId: string,
  mergeRequestIid: string | number,
  sha?: string,
  approvalPassword?: string
): Promise<GitLabMergeRequestApprovalState> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/approve`
  );

  const body: Record<string, string> = {};
  if (sha) {
    body.sha = sha;
  }
  if (approvalPassword) {
    body.approval_password = approvalPassword;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(body),
  });

  await handleGitLabError(response);
  return parseApprovalsResponse(await response.json());
}

/**
 * Unapprove a previously approved merge request
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string | number} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<GitLabMergeRequestApprovalState>} The approval state after unapproving
 */
async function unapproveMergeRequest(
  projectId: string,
  mergeRequestIid: string | number
): Promise<GitLabMergeRequestApprovalState> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/unapprove`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({}),
  });

  await handleGitLabError(response);
  return parseApprovalsResponse(await response.json());
}

/**
 * Get the approval state of a merge request
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string | number} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<GitLabMergeRequestApprovalState>} The approval state
 */
async function getMergeRequestApprovalState(
  projectId: string,
  mergeRequestIid: string | number
): Promise<GitLabMergeRequestApprovalState> {
  projectId = decodeURIComponent(projectId);
  const approvalStateUrl = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/approval_state`
  );

  const approvalStateResponse = await fetch(approvalStateUrl.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  if (approvalStateResponse.status === 404) {
    return getMergeRequestApprovalsFallback(projectId, mergeRequestIid);
  }

  await handleGitLabError(approvalStateResponse);

  const parsedApprovalState = GitLabMergeRequestApprovalStateSchema.parse(
    await approvalStateResponse.json()
  );
  const approvedByUsers = getUniqueApprovalUsers(
    (parsedApprovalState.rules || []).flatMap(rule => rule.approved_by || [])
  );
  const approvedByUsernames = approvedByUsers.map(user => user.username);

  return {
    ...parsedApprovalState,
    approved_by: approvedByUsers,
    approved_by_usernames: approvedByUsernames,
    source_endpoint: "approval_state",
  };
}

/**
 * Get the conflicts of a merge request
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string | number} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<Record<string, unknown>>} The merge request conflicts
 */
async function getMergeRequestConflicts(
  projectId: string,
  mergeRequestIid: string | number
): Promise<Record<string, unknown>> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/conflicts`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  await handleGitLabError(response);

  return (await response.json()) as Record<string, unknown>;
}

async function getMergeRequestApprovalsFallback(
  projectId: string,
  mergeRequestIid: string | number
): Promise<GitLabMergeRequestApprovalState> {
  const approvalsUrl = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/merge_requests/${mergeRequestIid}/approvals`
  );

  const approvalsResponse = await fetch(approvalsUrl.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  await handleGitLabError(approvalsResponse);
  return parseApprovalsResponse(await approvalsResponse.json());
}

/**
 * Parse the response from POST /approve and POST /unapprove endpoints.
 * These endpoints return the approvals format (approved_by contains nested
 * { user: {...} } objects), which must be converted to the flat format
 * used by GitLabMergeRequestApprovalStateSchema.
 */
function parseApprovalsResponse(responseJson: unknown): GitLabMergeRequestApprovalState {
  const parsedApprovals = GitLabMergeRequestApprovalsResponseSchema.parse(responseJson);
  const approvedByUsers = getUniqueApprovalUsers(
    (parsedApprovals.approved_by || []).map(approvedByEntry => approvedByEntry.user)
  );
  const approvedByUsernames = approvedByUsers.map(user => user.username);

  return GitLabMergeRequestApprovalStateSchema.parse({
    approved: parsedApprovals.approved,
    user_has_approved: parsedApprovals.user_has_approved,
    user_can_approve: parsedApprovals.user_can_approve,
    approved_by: approvedByUsers,
    approved_by_usernames: approvedByUsernames,
    source_endpoint: "approvals",
  });
}

function getUniqueApprovalUsers(users: GitLabApprovalUser[]): GitLabApprovalUser[] {
  const uniqueUsers = new Map<string, GitLabApprovalUser>();

  for (const user of users) {
    if (!uniqueUsers.has(user.id)) {
      uniqueUsers.set(user.id, user);
    }
  }

  return [...uniqueUsers.values()];
}

function inferMergeRequestApproved(
  rules: GitLabMergeRequestApprovalState["rules"]
): boolean | null {
  if (!rules || rules.length === 0) {
    return null;
  }

  if (rules.some(rule => typeof rule.approved !== "boolean")) {
    return null;
  }

  return rules.every(rule => rule.approved === true);
}

/**
 * Create a new note (comment) on an issue or merge request
 * 📦 새로운 함수: createNote - 이슈 또는 병합 요청에 노트(댓글)를 추가하는 함수
 * (New function: createNote - Function to add a note (comment) to an issue or merge request)
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {"issue" | "merge_request"} noteableType - The type of the item to add a note to (issue or merge_request)
 * @param {number} noteableIid - The internal ID of the issue or merge request
 * @param {string} body - The content of the note
 * @returns {Promise<any>} The created note
 */
async function createNote(
  projectId: string,
  noteableType: "issue" | "merge_request", // specifies 'issue' or 'merge_request' type
  noteableIid: number | string,
  body: string
): Promise<any> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  // ⚙️ Response type can be adjusted according to the GitLab API documentation
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/${noteableType}s/${noteableIid}/notes` // Using plural form (issues/merge_requests) as per GitLab API documentation
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify({ body }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  return await response.json();
}

/**
 * List draft notes for a merge request
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<GitLabDraftNote[]>} Array of draft notes
 */
async function getDraftNote(
  project_id: string,
  merge_request_iid: string,
  draft_note_id: string
): Promise<GitLabDraftNote> {
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(project_id)}/merge_requests/${merge_request_iid}/draft_notes/${draft_note_id}`,
    { ...getFetchConfig() }
  );

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  const data = await response.json();
  return GitLabDraftNoteSchema.parse(data);
}

async function listDraftNotes(
  projectId: string,
  mergeRequestIid: number | string
): Promise<GitLabDraftNote[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  const data = await response.json();
  return z.array(GitLabDraftNoteSchema).parse(data);
}

/**
 * Create a draft note for a merge request
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @param {string} body - The content of the draft note
 * @param {string} [inReplyToDiscussionId] - The ID of a discussion the draft note replies to
 * @param {MergeRequestThreadPosition} [position] - Position information for diff notes
 * @param {boolean} [resolveDiscussion] - Whether to resolve the discussion when publishing
 * @returns {Promise<GitLabDraftNote>} The created draft note
 */
async function createDraftNote(
  projectId: string,
  mergeRequestIid: number | string,
  body: string,
  inReplyToDiscussionId?: string,
  position?: MergeRequestThreadPosition,
  resolveDiscussion?: boolean
): Promise<GitLabDraftNote> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes`
  );

  const requestBody: any = { note: body };
  if (inReplyToDiscussionId) {
    requestBody.in_reply_to_discussion_id = inReplyToDiscussionId;
  }
  if (position) {
    requestBody.position = position;
  }
  if (resolveDiscussion !== undefined) {
    requestBody.resolve_discussion = resolveDiscussion;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(requestBody),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  const data = await response.json();
  return GitLabDraftNoteSchema.parse(data);
}

/**
 * Update an existing draft note
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @param {number|string} draftNoteId - The ID of the draft note
 * @param {string} [body] - The updated content of the draft note
 * @param {MergeRequestThreadPosition} [position] - Updated position information
 * @param {boolean} [resolveDiscussion] - Whether to resolve the discussion when publishing
 * @returns {Promise<GitLabDraftNote>} The updated draft note
 */
async function updateDraftNote(
  projectId: string,
  mergeRequestIid: number | string,
  draftNoteId: number | string,
  body?: string,
  position?: MergeRequestThreadPosition,
  resolveDiscussion?: boolean
): Promise<GitLabDraftNote> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes/${draftNoteId}`
  );

  const requestBody: any = {};
  if (body !== undefined) {
    requestBody.note = body;
  }
  if (position) {
    requestBody.position = position;
  }
  if (resolveDiscussion !== undefined) {
    requestBody.resolve_discussion = resolveDiscussion;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(requestBody),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  const data = await response.json();
  return GitLabDraftNoteSchema.parse(data);
}

/**
 * Delete a draft note
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @param {number|string} draftNoteId - The ID of the draft note
 * @returns {Promise<void>}
 */
async function deleteDraftNote(
  projectId: string,
  mergeRequestIid: number | string,
  draftNoteId: number | string
): Promise<void> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes/${draftNoteId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }
}

/**
 * Publish a single draft note
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @param {number|string} draftNoteId - The ID of the draft note
 * @returns {Promise<GitLabDiscussionNote>} The published note
 */
async function publishDraftNote(
  projectId: string,
  mergeRequestIid: number | string,
  draftNoteId: number | string
): Promise<GitLabDiscussionNote> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes/${draftNoteId}/publish`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  // Handle empty response (204 No Content) or successful response
  const responseText = await response.text();
  if (!responseText || responseText.trim() === "") {
    // Return a success indicator for empty responses
    return {
      id: draftNoteId.toString(),
      body: "Draft note published successfully",
      author: { id: "unknown", username: "unknown" },
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString(),
      system: false,
      noteable_id: mergeRequestIid.toString(),
      noteable_type: "MergeRequest",
    } as any;
  }

  try {
    const data = JSON.parse(responseText);
    return GitLabDiscussionNoteSchema.parse(data);
  } catch (parseError) {
    // If JSON parsing fails but the operation was successful (2xx status),
    // return a success indicator
    console.warn(`JSON parse error for successful publish operation: ${parseError}`);
    return {
      id: draftNoteId.toString(),
      body: "Draft note published successfully (response parse error)",
      author: { id: "unknown", username: "unknown" },
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString(),
      system: false,
      noteable_id: mergeRequestIid.toString(),
      noteable_type: "MergeRequest",
    } as any;
  }
}

/**
 * Publish all draft notes for a merge request
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number|string} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<GitLabDiscussionNote[]>} Array of published notes
 */
async function bulkPublishDraftNotes(
  projectId: string,
  mergeRequestIid: number | string
): Promise<GitLabDiscussionNote[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/draft_notes/bulk_publish`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST", // Changed from PUT to POST
    body: JSON.stringify({}), // Send empty body for POST request
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }

  // Handle empty response (204 No Content) or successful response
  const responseText = await response.text();
  if (!responseText || responseText.trim() === "") {
    // Return empty array for successful bulk publish with no content
    return [];
  }

  try {
    const data = JSON.parse(responseText);
    return z.array(GitLabDiscussionNoteSchema).parse(data);
  } catch (parseError) {
    // If JSON parsing fails but the operation was successful (2xx status),
    // return empty array indicating successful bulk publish
    console.warn(`JSON parse error for successful bulk publish operation: ${parseError}`);
    return [];
  }
}

async function resolveMergeRequestThread(
  projectId: string,
  mergeRequestIid: number | string,
  discussionId: string,
  resolved?: boolean
): Promise<void> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/discussions/${discussionId}`
  );

  if (resolved !== undefined) {
    url.searchParams.append("resolved", resolved ? "true" : "false");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorText}`);
  }
}

/**
 * Create a new thread on a merge request
 * 📦 새로운 함수: createMergeRequestThread - 병합 요청에 새로운 스레드(토론)를 생성하는 함수
 * (New function: createMergeRequestThread - Function to create a new thread (discussion) on a merge request)
 *
 * This function provides more capabilities than createNote, including the ability to:
 * - Create diff notes (comments on specific lines of code)
 * - Specify exact positions for comments
 * - Set creation timestamps
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request
 * @param {string} body - The content of the thread
 * @param {MergeRequestThreadPosition} [position] - Position information for diff notes
 * @param {string} [createdAt] - ISO 8601 formatted creation date
 * @returns {Promise<GitLabDiscussion>} The created discussion thread
 */
async function createMergeRequestThread(
  projectId: string,
  mergeRequestIid: number | string,
  body: string,
  position?: MergeRequestThreadPosition,
  createdAt?: string
): Promise<GitLabDiscussion> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/discussions`
  );

  const payload: Record<string, any> = { body };

  if (position) {
    payload.position = position;
  }

  if (createdAt) {
    payload.created_at = createdAt;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(payload),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDiscussionSchema.parse(data);
}

/**
 * List all versions of a merge request
 * 병합 요청의 모든 버전 목록 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request
 * @returns {Promise<GitLabMergeRequestVersion[]>} List of merge request versions
 */
async function listMergeRequestVersions(
  projectId: string,
  mergeRequestIid: number | string
): Promise<GitLabMergeRequestVersion[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/versions`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabMergeRequestVersionSchema).parse(data);
}

/**
 * Get a specific version of a merge request
 * 병합 요청의 특정 버전 상세 정보 조회
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} mergeRequestIid - The internal ID of the merge request
 * @param {number} versionId - The ID of the version
 * @returns {Promise<GitLabMergeRequestVersionDetail>} The merge request version details
 */
async function getMergeRequestVersion(
  projectId: string,
  mergeRequestIid: number | string,
  versionId: number | string,
  unidiff?: boolean
): Promise<GitLabMergeRequestVersionDetail> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/merge_requests/${mergeRequestIid}/versions/${versionId}`
  );

  if (unidiff !== undefined) {
    url.searchParams.append("unidiff", String(unidiff));
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabMergeRequestVersionDetailSchema.parse(data);
}

/**
 * List projects
 * 프로젝트 목록 조회
 *
 * @param {Object} options - Options for listing projects
 * @returns {Promise<GitLabProject[]>} List of projects
 */
async function listProjects(
  options: z.infer<typeof ListProjectsSchema> = {}
): Promise<GitLabProject[]> {
  // Construct the query parameters
  const params = new URLSearchParams();
  for (const [key, value] of Object.entries(options)) {
    if (value !== undefined && value !== null) {
      if (typeof value === "boolean") {
        params.append(key, value ? "true" : "false");
      } else {
        params.append(key, String(value));
      }
    }
  }

  // Make the API request
  const response = await fetch(`${getEffectiveApiUrl()}/projects?${params.toString()}`, {
    ...getFetchConfig(),
  });

  // Handle errors
  await handleGitLabError(response);

  // Parse and return the data
  const data = await response.json();
  return z.array(GitLabProjectSchema).parse(data);
}

/**
 * List labels for a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param options Optional parameters for listing labels
 * @returns Array of GitLab labels
 */
async function listLabels(
  projectId: string,
  options: Omit<z.infer<typeof ListLabelsSchema>, "project_id"> = {}
): Promise<GitLabLabel[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  // Construct the URL with project path
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/labels`
  );

  // Add query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (typeof value === "boolean") {
        url.searchParams.append(key, value ? "true" : "false");
      } else {
        url.searchParams.append(key, String(value));
      }
    }
  });

  // Make the API request
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  // Handle errors
  await handleGitLabError(response);

  // Parse and return the data
  const data = await response.json();
  return data as GitLabLabel[];
}

/**
 * Get a single label from a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param labelId The ID or name of the label
 * @param includeAncestorGroups Whether to include ancestor groups
 * @returns GitLab label
 */
async function getLabel(
  projectId: string,
  labelId: number | string,
  includeAncestorGroups?: boolean
): Promise<GitLabLabel> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/labels/${encodeURIComponent(String(labelId))}`
  );

  // Add query parameters
  if (includeAncestorGroups !== undefined) {
    url.searchParams.append("include_ancestor_groups", includeAncestorGroups ? "true" : "false");
  }

  // Make the API request
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  // Handle errors
  await handleGitLabError(response);

  // Parse and return the data
  const data = await response.json();
  return data as GitLabLabel;
}

/**
 * Create a new label in a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param options Options for creating the label
 * @returns Created GitLab label
 */
async function createLabel(
  projectId: string,
  options: Omit<z.infer<typeof CreateLabelSchema>, "project_id">
): Promise<GitLabLabel> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  // Make the API request
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/labels`,
    {
      ...getFetchConfig(),
      method: "POST",
      body: JSON.stringify(options),
    }
  );

  // Handle errors
  await handleGitLabError(response);

  // Parse and return the data
  const data = await response.json();
  return data as GitLabLabel;
}

/**
 * Update an existing label in a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param labelId The ID or name of the label to update
 * @param options Options for updating the label
 * @returns Updated GitLab label
 */
async function updateLabel(
  projectId: string,
  labelId: number | string,
  options: Omit<z.infer<typeof UpdateLabelSchema>, "project_id" | "label_id">
): Promise<GitLabLabel> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  // Make the API request
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/labels/${encodeURIComponent(String(labelId))}`,
    {
      ...getFetchConfig(),
      method: "PUT",
      body: JSON.stringify(options),
    }
  );

  // Handle errors
  await handleGitLabError(response);

  // Parse and return the data
  const data = await response.json();
  return data as GitLabLabel;
}

/**
 * Delete a label from a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param labelId The ID or name of the label to delete
 */
async function deleteLabel(projectId: string, labelId: number | string): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  // Make the API request
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/labels/${encodeURIComponent(String(labelId))}`,
    {
      ...getFetchConfig(),
      method: "DELETE",
    }
  );

  // Handle errors
  await handleGitLabError(response);
}

/**
 * List all projects in a GitLab group
 *
 * @param {z.infer<typeof ListGroupProjectsSchema>} options - Options for listing group projects
 * @returns {Promise<GitLabProject[]>} Array of projects in the group
 */
async function listGroupProjects(
  options: z.infer<typeof ListGroupProjectsSchema>
): Promise<GitLabProject[]> {
  const url = new URL(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(options.group_id)}/projects`
  );

  // Add optional parameters to URL
  if (options.include_subgroups) url.searchParams.append("include_subgroups", "true");
  if (options.search) url.searchParams.append("search", options.search);
  if (options.order_by) url.searchParams.append("order_by", options.order_by);
  if (options.sort) url.searchParams.append("sort", options.sort);
  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());
  if (options.archived !== undefined)
    url.searchParams.append("archived", options.archived.toString());
  if (options.visibility) url.searchParams.append("visibility", options.visibility);
  if (options.with_issues_enabled !== undefined)
    url.searchParams.append("with_issues_enabled", options.with_issues_enabled.toString());
  if (options.with_merge_requests_enabled !== undefined)
    url.searchParams.append(
      "with_merge_requests_enabled",
      options.with_merge_requests_enabled.toString()
    );
  if (options.min_access_level !== undefined)
    url.searchParams.append("min_access_level", options.min_access_level.toString());
  if (options.with_programming_language)
    url.searchParams.append("with_programming_language", options.with_programming_language);
  if (options.starred !== undefined) url.searchParams.append("starred", options.starred.toString());
  if (options.statistics !== undefined)
    url.searchParams.append("statistics", options.statistics.toString());
  if (options.with_custom_attributes !== undefined)
    url.searchParams.append("with_custom_attributes", options.with_custom_attributes.toString());
  if (options.with_security_reports !== undefined)
    url.searchParams.append("with_security_reports", options.with_security_reports.toString());

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const projects = await response.json();
  return GitLabProjectSchema.array().parse(projects);
}

// Webhook API helper functions

/**
 * Build the base URL for webhooks (project or group)
 */
function buildWebhookBaseUrl(projectId?: string, groupId?: string): string {
  if (projectId) {
    projectId = decodeURIComponent(projectId);
    return `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/hooks`;
  }
  const decodedGroupId = decodeURIComponent(groupId!);
  return `${getEffectiveApiUrl()}/groups/${encodeURIComponent(decodedGroupId)}/hooks`;
}

/**
 * List webhooks for a project or group
 */
async function listWebhooks(
  options: z.infer<typeof ListWebhooksSchema>
): Promise<unknown[]> {
  const url = new URL(buildWebhookBaseUrl(options.project_id, options.group_id));

  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());

  const response = await fetch(url.toString(), { ...getFetchConfig() });
  await handleGitLabError(response);
  return (await response.json()) as unknown[];
}



/**
 * Fetch a single page of webhook events
 */
async function fetchWebhookEventsPage(
  baseUrl: string,
  page: number,
  perPage: number,
  status?: string | number
): Promise<Record<string, unknown>[]> {
  const url = new URL(baseUrl);
  url.searchParams.set("page", page.toString());
  url.searchParams.set("per_page", perPage.toString());
  if (status !== undefined) url.searchParams.append("status", String(status));

  const response = await fetch(url.toString(), { ...getFetchConfig() });
  await handleGitLabError(response);
  return (await response.json()) as Record<string, unknown>[];
}

/**
 * List webhook events for a project or group webhook
 */
async function listWebhookEvents(
  options: z.infer<typeof ListWebhookEventsSchema>
): Promise<unknown[]> {
  const eventsUrl = `${buildWebhookBaseUrl(options.project_id, options.group_id)}/${options.hook_id}/events`;

  const events = await fetchWebhookEventsPage(
    eventsUrl,
    options.page ?? 1,
    options.per_page ?? 20,
    options.status
  );
  return options.summary ? summarizeWebhookEvents(events) : events;
}

/**
 * Get a specific webhook event by ID (searches up to 500 recent events)
 */
async function getWebhookEvent(
  options: z.infer<typeof GetWebhookEventSchema>
): Promise<Record<string, unknown> | null> {
  const eventsUrl = `${buildWebhookBaseUrl(options.project_id, options.group_id)}/${options.hook_id}/events`;
  // GitLab enforces max per_page=20 for webhook events
  const perPage = 20;

  if (options.page) {
    // Direct page lookup — single API call
    const events = await fetchWebhookEventsPage(eventsUrl, options.page, perPage);
    const match = events.find(e => e.id === options.event_id);
    return match ?? null;
  }

  // Auto-paginate up to 500 events
  const maxPages = 25;
  for (let page = 1; page <= maxPages; page++) {
    const events = await fetchWebhookEventsPage(eventsUrl, page, perPage);
    const match = events.find(e => e.id === options.event_id);
    if (match) return match;
    if (events.length < perPage) break;
  }
  return null;
}

// Wiki API helper functions
/**
 * List wiki pages in a project
 */
async function listWikiPages(
  projectId: string,
  options: Omit<ListWikiPagesOptions, "project_id"> = {}
): Promise<GitLabWikiPage[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/wikis`
  );
  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());
  if (options.with_content)
    url.searchParams.append("with_content", options.with_content.toString());
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.array().parse(data);
}

/**
 * Get a specific wiki page
 */
async function getWikiPage(projectId: string, slug: string): Promise<GitLabWikiPage> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/wikis/${encodeURIComponent(slug)}`,
    { ...getFetchConfig() }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Create a new wiki page
 */
async function createWikiPage(
  projectId: string,
  title: string,
  content: string,
  format?: string
): Promise<GitLabWikiPage> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const body: Record<string, any> = { title, content };
  if (format) body.format = format;
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/wikis`,
    {
      ...getFetchConfig(),
      method: "POST",
      body: JSON.stringify(body),
    }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Update an existing wiki page
 */
async function updateWikiPage(
  projectId: string,
  slug: string,
  title?: string,
  content?: string,
  format?: string
): Promise<GitLabWikiPage> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const body: Record<string, any> = {};
  if (title) body.title = title;
  if (content) body.content = content;
  if (format) body.format = format;
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/wikis/${encodeURIComponent(slug)}`,
    {
      ...getFetchConfig(),
      method: "PUT",
      body: JSON.stringify(body),
    }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Delete a wiki page
 */
async function deleteWikiPage(projectId: string, slug: string): Promise<void> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/wikis/${encodeURIComponent(slug)}`,
    {
      ...getFetchConfig(),
      method: "DELETE",
    }
  );
  await handleGitLabError(response);
}

/**
 * List wiki pages in a GitLab group
 */
async function listGroupWikiPages(
  groupId: string,
  options: Omit<ListGroupWikiPagesOptions, "group_id"> = {}
): Promise<GitLabWikiPage[]> {
  groupId = decodeURIComponent(groupId); // Decode group ID
  const url = new URL(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/wikis`
  );
  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());
  if (options.with_content)
    url.searchParams.append("with_content", options.with_content.toString());
  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.array().parse(data);
}

/**
 * Get a specific group wiki page
 */
async function getGroupWikiPage(groupId: string, slug: string): Promise<GitLabWikiPage> {
  groupId = decodeURIComponent(groupId); // Decode group ID
  const response = await fetch(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/wikis/${encodeURIComponent(slug)}`,
    { ...getFetchConfig() }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Create a new group wiki page
 */
async function createGroupWikiPage(
  groupId: string,
  title: string,
  content: string,
  format?: string
): Promise<GitLabWikiPage> {
  groupId = decodeURIComponent(groupId); // Decode group ID
  const body: Record<string, any> = { title, content };
  if (format) body.format = format;
  const response = await fetch(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/wikis`,
    {
      ...getFetchConfig(),
      method: "POST",
      body: JSON.stringify(body),
    }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Update an existing group wiki page
 */
async function updateGroupWikiPage(
  groupId: string,
  slug: string,
  title?: string,
  content?: string,
  format?: string
): Promise<GitLabWikiPage> {
  groupId = decodeURIComponent(groupId); // Decode group ID
  const body: Record<string, any> = {};
  if (title) body.title = title;
  if (content) body.content = content;
  if (format) body.format = format;
  const response = await fetch(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/wikis/${encodeURIComponent(slug)}`,
    {
      ...getFetchConfig(),
      method: "PUT",
      body: JSON.stringify(body),
    }
  );
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabWikiPageSchema.parse(data);
}

/**
 * Delete a group wiki page
 */
async function deleteGroupWikiPage(groupId: string, slug: string): Promise<void> {
  groupId = decodeURIComponent(groupId); // Decode group ID
  const response = await fetch(
    `${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/wikis/${encodeURIComponent(slug)}`,
    {
      ...getFetchConfig(),
      method: "DELETE",
    }
  );
  await handleGitLabError(response);
}

/**
 * List pipelines in a GitLab project
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {ListPipelinesOptions} options - Options for filtering pipelines
 * @returns {Promise<GitLabPipeline[]>} List of pipelines
 */
async function listPipelines(
  projectId: string,
  options: Omit<ListPipelinesOptions, "project_id"> = {}
): Promise<GitLabPipeline[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines`
  );

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabPipelineSchema).parse(data);
}

/**
 * Get details of a specific pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} pipelineId - The ID of the pipeline
 * @returns {Promise<GitLabPipeline>} Pipeline details
 */
async function getPipeline(
  projectId: string,
  pipelineId: number | string
): Promise<GitLabPipeline> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${pipelineId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Pipeline not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineSchema.parse(data);
}

/**
 * List deployments in a GitLab project
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {ListDeploymentsOptions} options - Options for filtering deployments
 * @returns {Promise<GitLabDeployment[]>} List of deployments
 */
async function listDeployments(
  projectId: string,
  options: Omit<ListDeploymentsOptions, "project_id"> = {}
): Promise<GitLabDeployment[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/deployments`
  );

  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabDeploymentSchema).parse(data);
}

/**
 * Get details of a specific deployment
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number | string} deploymentId - The ID of the deployment
 * @returns {Promise<GitLabDeployment>} Deployment details
 */
async function getDeployment(
  projectId: string,
  deploymentId: number | string
): Promise<GitLabDeployment> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/deployments/${deploymentId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Deployment not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabDeploymentSchema.parse(data);
}

/**
 * List environments in a GitLab project
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {ListEnvironmentsOptions} options - Options for filtering environments
 * @returns {Promise<GitLabEnvironment[]>} List of environments
 */
async function listEnvironments(
  projectId: string,
  options: Omit<ListEnvironmentsOptions, "project_id"> = {}
): Promise<GitLabEnvironment[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/environments`
  );

  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabEnvironmentSchema).parse(data);
}

/**
 * Get details of a specific environment
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number | string} environmentId - The ID of the environment
 * @returns {Promise<GitLabEnvironment>} Environment details
 */
async function getEnvironment(
  projectId: string,
  environmentId: number | string
): Promise<GitLabEnvironment> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/environments/${environmentId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Environment not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabEnvironmentSchema.parse(data);
}

/**
 * List all jobs in a specific pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} pipelineId - The ID of the pipeline
 * @param {Object} options - Options for filtering jobs
 * @returns {Promise<GitLabPipelineJob[]>} List of pipeline jobs
 */
async function listPipelineJobs(
  projectId: string,
  pipelineId: number | string,
  options: Omit<ListPipelineJobsOptions, "project_id" | "pipeline_id"> = {}
): Promise<GitLabPipelineJob[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${pipelineId}/jobs`
  );

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (typeof value === "boolean") {
        url.searchParams.append(key, value ? "true" : "false");
      } else {
        url.searchParams.append(key, value.toString());
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Pipeline not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabPipelineJobSchema).parse(data);
}

/**
 * List all trigger jobs (bridges) in a specific pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} pipelineId - The ID of the pipeline
 * @param {Object} options - Options for filtering trigger jobs
 * @returns {Promise<GitLabPipelineTriggerJob[]>} List of pipeline trigger jobs
 */
async function listPipelineTriggerJobs(
  projectId: string,
  pipelineId: number | string,
  options: Omit<ListPipelineTriggerJobsOptions, "project_id" | "pipeline_id"> = {}
): Promise<GitLabPipelineTriggerJob[]> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${pipelineId}/bridges`
  );

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (typeof value === "boolean") {
        url.searchParams.append(key, value ? "true" : "false");
      } else {
        url.searchParams.append(key, value.toString());
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Pipeline not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabPipelineTriggerJobSchema).parse(data);
}

async function getPipelineJob(
  projectId: string,
  jobId: number | string
): Promise<GitLabPipelineJob> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Job not found`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineJobSchema.parse(data);
}

/**
 * Get the output/trace of a pipeline job
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} jobId - The ID of the job
 * @param {number} limit - Maximum number of lines to return from the end (default: 1000)
 * @param {number} offset - Number of lines to skip from the end (default: 0)
 * @returns {Promise<string>} The job output/trace
 */
async function getPipelineJobOutput(
  projectId: string,
  jobId: number | string,
  limit?: number,
  offset?: number
): Promise<string> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}/trace`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    headers: {
      ...BASE_HEADERS,
      ...buildAuthHeaders(),
      Accept: "text/plain", // Override Accept header to get plain text
    },
  });

  if (response.status === 404) {
    throw new Error(`Job trace not found or job is not finished yet`);
  }

  await handleGitLabError(response);
  const fullTrace = await response.text();

  // Apply client-side pagination to limit context window usage
  if (limit !== undefined || offset !== undefined) {
    const lines = fullTrace.split("\n");
    const startOffset = offset || 0;
    const maxLines = limit || 1000;

    // Return lines from the end, skipping offset lines and limiting to maxLines
    const startIndex = Math.max(0, lines.length - startOffset - maxLines);
    const endIndex = lines.length - startOffset;

    const selectedLines = lines.slice(startIndex, endIndex);
    const result = selectedLines.join("\n");

    // Add metadata about truncation
    if (startIndex > 0 || endIndex < lines.length) {
      const totalLines = lines.length;
      const shownLines = selectedLines.length;
      const skippedFromStart = startIndex;
      const skippedFromEnd = startOffset;

      return `[Log truncated: showing ${shownLines} of ${totalLines} lines, skipped ${skippedFromStart} from start, ${skippedFromEnd} from end]\n\n${result}`;
    }

    return result;
  }

  return fullTrace;
}

/**
 * List artifact files in a job's artifacts archive
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} jobId - The ID of the job
 * @param {Object} options - Options for listing artifacts
 * @returns {Promise<GitLabArtifactEntry[]>} List of artifact entries
 */
async function listJobArtifacts(
  projectId: string,
  jobId: string,
  options: Omit<z.infer<typeof ListJobArtifactsSchema>, "project_id" | "job_id"> = {}
): Promise<GitLabArtifactEntry[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}/artifacts/tree`
  );

  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (typeof value === "boolean") {
        url.searchParams.append(key, value ? "true" : "false");
      } else {
        url.searchParams.append(key, value.toString());
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
  }

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabArtifactEntrySchema).parse(data);
}

/**
 * Download the entire artifact archive for a job and save to disk
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} jobId - The ID of the job
 * @param {string} localPath - Optional local directory to save the archive
 * @returns {Promise<string>} The path where the artifact archive was saved
 */
async function downloadJobArtifacts(
  projectId: string,
  jobId: string,
  localPath?: string
): Promise<string> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/jobs/${jobId}/artifacts`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Job artifacts not found. The job may not have produced artifacts or the job ID is invalid.`);
  }

  await handleGitLabError(response);

  const buffer = await response.arrayBuffer();
  const filename = `artifacts_job_${jobId}.zip`;
  const savePath = localPath ? path.join(localPath, filename) : filename;
  fs.mkdirSync(path.dirname(savePath), { recursive: true });

  fs.writeFileSync(savePath, Buffer.from(buffer));

  return savePath;
}

/**
 * Download a single file from a job's artifacts
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} jobId - The ID of the job
 * @param {string} artifactPath - Path to the file within the artifacts archive
 * @returns {Promise<string>} The file content as text
 */
async function getJobArtifactFile(
  projectId: string,
  jobId: string,
  artifactPath: string
): Promise<string> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const encodedArtifactPath = artifactPath
    .split("/")
    .map(segment => encodeURIComponent(segment))
    .join("/");

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/jobs/${jobId}/artifacts/${encodedArtifactPath}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  if (response.status === 404) {
    throw new Error(`Artifact file not found: ${artifactPath}`);
  }

  await handleGitLabError(response);

  return await response.text();
}

/**
 * Create a new pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} ref - The branch or tag to run the pipeline on
 * @param {Array} variables - Optional variables for the pipeline
 * @param {Record<string, string>} inputs - Optional input parameters for the pipeline
 * @returns {Promise<GitLabPipeline>} The created pipeline
 */
async function createPipeline(
  projectId: string,
  ref: string,
  variables?: Array<{ key: string; value: string }>,
  inputs?: Record<string, string>
): Promise<GitLabPipeline> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipeline`
  );

  const body: any = { ref };
  if (variables && variables.length > 0) {
    body.variables = variables;
  }
  if (inputs && Object.keys(inputs).length > 0) {
    body.inputs = inputs;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(body),
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineSchema.parse(data);
}

/**
 * Retry a pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} pipelineId - The ID of the pipeline to retry
 * @returns {Promise<GitLabPipeline>} The retried pipeline
 */
async function retryPipeline(
  projectId: string,
  pipelineId: number | string
): Promise<GitLabPipeline> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${pipelineId}/retry`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineSchema.parse(data);
}

/**
 * Cancel a pipeline
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} pipelineId - The ID of the pipeline to cancel
 * @returns {Promise<GitLabPipeline>} The canceled pipeline
 */
async function cancelPipeline(
  projectId: string,
  pipelineId: number | string
): Promise<GitLabPipeline> {
  projectId = decodeURIComponent(projectId); // Decode project ID
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/pipelines/${pipelineId}/cancel`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineSchema.parse(data);
}

/**
 * Run a manual job
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} jobId - The ID of the job to run
 * @param {Object} variables - Optional job variables
 * @returns {Promise<GitLabPipelineJob>} The run job
 */
async function playPipelineJob(
  projectId: string,
  jobId: number | string,
  variables?: Array<{ key: string; value: string }>
): Promise<GitLabPipelineJob> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}/play`
  );

  const body: any = {};
  if (variables && variables.length > 0) {
    body.job_variables_attributes = variables;
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineJobSchema.parse(data);
}

/**
 * Retry a job
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} jobId - The ID of the job to retry
 * @returns {Promise<GitLabPipelineJob>} The retried job
 */
async function retryPipelineJob(
  projectId: string,
  jobId: number | string
): Promise<GitLabPipelineJob> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}/retry`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineJobSchema.parse(data);
}

/**
 * Cancel a job
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} jobId - The ID of the job to cancel
 * @param {boolean} force - Force cancellation of the job
 * @returns {Promise<GitLabPipelineJob>} The canceled job
 */
async function cancelPipelineJob(
  projectId: string,
  jobId: number | string,
  force?: boolean
): Promise<GitLabPipelineJob> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/jobs/${jobId}/cancel`
  );

  if (force !== undefined) {
    url.searchParams.append("force", force.toString());
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabPipelineJobSchema.parse(data);
}

/**
 * Get the repository tree for a project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {GetRepositoryTreeOptions} options - Options for the tree
 * @returns {Promise<GitLabTreeItem[]>}
 */
async function getRepositoryTree(options: GetRepositoryTreeOptions): Promise<GitLabTreeItem[]> {
  options.project_id = decodeURIComponent(options.project_id); // Decode project_id within options
  const queryParams = new URLSearchParams();
  if (options.path) queryParams.append("path", options.path);
  if (options.ref) queryParams.append("ref", options.ref);
  if (options.recursive) queryParams.append("recursive", "true");
  if (options.per_page) queryParams.append("per_page", options.per_page.toString());
  if (options.page_token) queryParams.append("page_token", options.page_token);
  if (options.pagination) queryParams.append("pagination", options.pagination);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(options.project_id)
    )}/repository/tree?${queryParams.toString()}`,
    { ...getFetchConfig() }
  );

  if (response.status === 404) {
    throw new Error("Repository or path not found");
  }

  if (!response.ok) {
    throw new Error(`Failed to get repository tree: ${response.statusText}`);
  }

  const data = await response.json();
  return z.array(GitLabTreeItemSchema).parse(data);
}

/**
 * List project milestones in a GitLab project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {Object} options - Options for listing milestones
 * @returns {Promise<GitLabMilestones[]>} List of milestones
 */
async function listProjectMilestones(
  projectId: string,
  options: Omit<z.infer<typeof ListProjectMilestonesSchema>, "project_id">
): Promise<GitLabMilestones[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones`
  );

  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      if (key === "iids" && Array.isArray(value) && value.length > 0) {
        value.forEach(iid => {
          url.searchParams.append("iids[]", iid.toString());
        });
      } else if (value !== undefined) {
        url.searchParams.append(key, value.toString());
      }
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabMilestonesSchema).parse(data);
}

/**
 * Get a single milestone in a GitLab project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<GitLabMilestones>} Milestone details
 */
async function getProjectMilestone(
  projectId: string,
  milestoneId: number | string
): Promise<GitLabMilestones> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${milestoneId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabMilestonesSchema.parse(data);
}

/**
 * Create a new milestone in a GitLab project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {Object} options - Options for creating a milestone
 * @returns {Promise<GitLabMilestones>} Created milestone
 */
async function createProjectMilestone(
  projectId: string,
  options: Omit<z.infer<typeof CreateProjectMilestoneSchema>, "project_id">
): Promise<GitLabMilestones> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
    body: JSON.stringify(options),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabMilestonesSchema.parse(data);
}

/**
 * Edit an existing milestone in a GitLab project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @param {Object} options - Options for editing a milestone
 * @returns {Promise<GitLabMilestones>} Updated milestone
 */
async function editProjectMilestone(
  projectId: string,
  milestoneId: number | string,
  options: Omit<z.infer<typeof EditProjectMilestoneSchema>, "project_id" | "milestone_id">
): Promise<GitLabMilestones> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${milestoneId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "PUT",
    body: JSON.stringify(options),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabMilestonesSchema.parse(data);
}

/**
 * Delete a milestone from a GitLab project
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<void>}
 */
async function deleteProjectMilestone(
  projectId: string,
  milestoneId: number | string
): Promise<void> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${milestoneId}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "DELETE",
  });
  await handleGitLabError(response);
}

/**
 * Get all issues assigned to a single milestone
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<GitLabIssue[]>} List of issues
 */
async function getMilestoneIssues(
  projectId: string,
  milestoneId: number | string
): Promise<GitLabIssue[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${milestoneId}/issues`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabIssueSchema).parse(data);
}

/**
 * Get all merge requests assigned to a single milestone
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<GitLabMergeRequest[]>} List of merge requests
 */
async function getMilestoneMergeRequests(
  projectId: string,
  milestoneId: number | string
): Promise<GitLabMergeRequest[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/milestones/${milestoneId}/merge_requests`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabMergeRequestSchema).parse(data);
}

/**
 * Promote a project milestone to a group milestone
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<GitLabMilestones>} Promoted milestone
 */
async function promoteProjectMilestone(
  projectId: string,
  milestoneId: number | string
): Promise<GitLabMilestones> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/milestones/${milestoneId}/promote`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "POST",
  });
  await handleGitLabError(response);
  const data = await response.json();
  return GitLabMilestonesSchema.parse(data);
}

/**
 * Get all burndown chart events for a single milestone
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {number} milestoneId - The ID of the milestone
 * @returns {Promise<any[]>} Burndown chart events
 */
async function getMilestoneBurndownEvents(
  projectId: string,
  milestoneId: number | string
): Promise<any[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(
      getEffectiveProjectId(projectId)
    )}/milestones/${milestoneId}/burndown_events`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });
  await handleGitLabError(response);
  const data = await response.json();
  return data as any[];
}

/**
 * Get a single user from GitLab
 *
 * @param {string} username - The username to look up
 * @returns {Promise<GitLabUser | null>} The user data or null if not found
 */
async function getUser(username: string): Promise<GitLabUser | null> {
  try {
    const url = new URL(`${getEffectiveApiUrl()}/users`);
    url.searchParams.append("username", username);

    const response = await fetch(url.toString(), {
      ...getFetchConfig(),
    });

    await handleGitLabError(response);

    const users = await response.json();

    // GitLab returns an array of users that match the username
    if (Array.isArray(users) && users.length > 0) {
      // Find exact match for username (case-sensitive)
      const exactMatch = users.find(user => user.username === username);
      if (exactMatch) {
        return GitLabUserSchema.parse(exactMatch);
      }
    }

    // No matching user found
    return null;
  } catch (error) {
    logger.error(`Error fetching user by username '${username}':`, error);
    return null;
  }
}

/**
 * Get multiple users from GitLab
 *
 * @param {string[]} usernames - Array of usernames to look up
 * @returns {Promise<GitLabUsersResponse>} Object with usernames as keys and user objects or null as values
 */
async function getUsers(usernames: string[]): Promise<GitLabUsersResponse> {
  const users: Record<string, GitLabUser | null> = {};

  // Process usernames sequentially to avoid rate limiting
  for (const username of usernames) {
    try {
      const user = await getUser(username);
      users[username] = user;
    } catch (error) {
      logger.error(`Error processing username '${username}':`, error);
      users[username] = null;
    }
  }

  return GitLabUsersResponseSchema.parse(users);
}

/**
 * List repository commits
 * 저장소 커밋 목록 조회
 *
 * @param {string} projectId - Project ID or URL-encoded path
 * @param {ListCommitsOptions} options - List commits options
 * @returns {Promise<GitLabCommit[]>} List of commits
 */
async function listCommits(
  projectId: string,
  options: Omit<ListCommitsOptions, "project_id"> = {}
): Promise<GitLabCommit[]> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/commits`
  );

  // Add query parameters
  if (options.ref_name) url.searchParams.append("ref_name", options.ref_name);
  if (options.since) url.searchParams.append("since", options.since);
  if (options.until) url.searchParams.append("until", options.until);
  if (options.path) url.searchParams.append("path", options.path);
  if (options.author) url.searchParams.append("author", options.author);
  if (options.all) url.searchParams.append("all", options.all.toString());
  if (options.with_stats) url.searchParams.append("with_stats", options.with_stats.toString());
  if (options.first_parent)
    url.searchParams.append("first_parent", options.first_parent.toString());
  if (options.order) url.searchParams.append("order", options.order);
  if (options.trailers) url.searchParams.append("trailers", options.trailers.toString());
  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();
  return z.array(GitLabCommitSchema).parse(data);
}

/**
 * Get a single commit
 * 단일 커밋 정보 조회
 *
 * @param {string} projectId - Project ID or URL-encoded path
 * @param {string} sha - The commit hash or name of a repository branch or tag
 * @param {boolean} [stats] - Include commit stats
 * @returns {Promise<GitLabCommit>} The commit details
 */
async function getCommit(projectId: string, sha: string, stats?: boolean): Promise<GitLabCommit> {
  projectId = decodeURIComponent(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/commits/${encodeURIComponent(sha)}`
  );

  if (stats) {
    url.searchParams.append("stats", "true");
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabCommitSchema.parse(data);
}

/**
 * Get commit diff
 * 커밋 변경사항 조회
 *
 * @param {string} projectId - Project ID or URL-encoded path
 * @param {string} sha - The commit hash or name of a repository branch or tag
 * @param {boolean} [full_diff] - Whether to return the full diff or only first page
 * @returns {Promise<GitLabMergeRequestDiff[]>} The commit diffs
 */
async function getCommitDiff(
  projectId: string,
  sha: string,
  full_diff?: boolean
): Promise<GitLabMergeRequestDiff[]> {
  projectId = decodeURIComponent(projectId);
  const baseUrl = `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/commits/${encodeURIComponent(sha)}/diff`;

  let allDiffs: GitLabMergeRequestDiff[] = [];
  let page = 1;

  while (true) {
    const url = new URL(baseUrl);

    if (full_diff) {
      url.searchParams.append("page", page.toString());
    }

    const response = await fetch(url.toString(), {
      ...getFetchConfig(),
    });

    await handleGitLabError(response);

    const data = await response.json();
    const diffs = z.array(GitLabDiffSchema).parse(data);

    allDiffs.push(...diffs);

    if (!full_diff) {
      break;
    }

    if (diffs.length < GITLAB_COMMIT_FILES_PER_PAGE) {
      break;
    }

    page++;
  }

  return allDiffs;
}

/**
 * Get the current authenticated user
 * 현재 인증된 사용자 가져오기
 *
 * @returns {Promise<GitLabUser>} The current user
 */
async function getCurrentUser(): Promise<GitLabUser> {
  const response = await fetch(`${getEffectiveApiUrl()}/user`, getFetchConfig());

  await handleGitLabError(response);
  const data = await response.json();
  return GitLabUserSchema.parse(data);
}

/**
 * List issues assigned to the current authenticated user
 * 현재 인증된 사용자에게 할당된 이슈 목록 조회
 *
 * @param {MyIssuesOptions} options - Options for filtering issues
 * @returns {Promise<GitLabIssue[]>} List of issues assigned to the current user
 */
async function myIssues(options: MyIssuesOptions = {}): Promise<GitLabIssue[]> {
  // Get current user to find their username
  const currentUser = await getCurrentUser();

  // Use getEffectiveProjectId to handle project ID resolution
  const effectiveProjectId = getEffectiveProjectId(options.project_id || "");

  // Use listIssues with assignee_username filter
  let listIssuesOptions: Omit<z.infer<typeof ListIssuesSchema>, "project_id"> = {
    state: options.state || "opened", // Default to "opened" if not specified
    labels: options.labels,
    milestone: options.milestone,
    search: options.search,
    created_after: options.created_after,
    created_before: options.created_before,
    updated_after: options.updated_after,
    updated_before: options.updated_before,
    per_page: options.per_page,
    page: options.page,
  };

  if (currentUser.username) {
    listIssuesOptions.assignee_username = [currentUser.username];
  } else {
    listIssuesOptions.assignee_id = currentUser.id;
  }
  return listIssues(effectiveProjectId, listIssuesOptions);
}

/**
 * List members of a GitLab project
 * GitLab 프로젝트 멤버 목록 조회
 *
 * @param {string} projectId - Project ID or URL-encoded path
 * @param {Omit<ListProjectMembersOptions, "project_id">} options - Options for filtering members
 * @returns {Promise<GitLabProjectMember[]>} List of project members
 */
async function listProjectMembers(
  projectId: string,
  options: Omit<ListProjectMembersOptions, "project_id"> = {}
): Promise<GitLabProjectMember[]> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const membersPath = options.include_inheritance ? "members/all" : "members";
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/${membersPath}`
  );

  // Add query parameters
  if (options.query) url.searchParams.append("query", options.query);
  if (options.user_ids) {
    options.user_ids.forEach(id => url.searchParams.append("user_ids[]", id.toString()));
  }
  if (options.skip_users) {
    options.skip_users.forEach(id => url.searchParams.append("skip_users[]", id.toString()));
  }
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());
  if (options.page) url.searchParams.append("page", options.page.toString());

  const response = await fetch(url.toString(), getFetchConfig());

  await handleGitLabError(response);
  const data = await response.json();
  return z.array(GitLabProjectMemberSchema).parse(data);
}

/**
 * list group iterations
 *
 * @param {string} groupId
 * @param {Omit<ListGroupIterationsOptions, "group_id">} options
 * @returns {Promise<GetIt[]>}
 */
async function listGroupIterations(
  groupId: string,
  options: Omit<z.infer<typeof ListGroupIterationsSchema>, "group_id"> = {}
): Promise<GroupIteration[]> {
  groupId = decodeURIComponent(groupId);
  const url = new URL(`${getEffectiveApiUrl()}/groups/${encodeURIComponent(groupId)}/iterations`);

  // クエリパラメータの追加
  if (options.state) url.searchParams.append("state", options.state);
  if (options.search) url.searchParams.append("search", options.search);
  if (options.search_in) url.searchParams.append("in", options.search_in.join(","));
  if (options.include_ancestors !== undefined)
    url.searchParams.append("include_ancestors", options.include_ancestors.toString());
  if (options.include_descendants !== undefined)
    url.searchParams.append("include_descendants", options.include_descendants.toString());
  if (options.updated_before) url.searchParams.append("updated_before", options.updated_before);
  if (options.updated_after) url.searchParams.append("updated_after", options.updated_after);
  if (options.page) url.searchParams.append("page", options.page.toString());
  if (options.per_page) url.searchParams.append("per_page", options.per_page.toString());

  const response = await fetch(url.toString(), getFetchConfig());

  if (!response.ok) {
    await handleGitLabError(response);
  }

  const data = await response.json();
  return z.array(GroupIteration).parse(data);
}

/**
 * Upload a file to a GitLab project for use in markdown content
 *
 * @param {string} projectId - The ID or URL-encoded path of the project
 * @param {string} filePath - Path to the local file to upload
 * @returns {Promise<GitLabMarkdownUpload>} The upload response
 */
async function markdownUpload(projectId: string, filePath: string): Promise<GitLabMarkdownUpload> {
  projectId = decodeURIComponent(projectId);
  const effectiveProjectId = getEffectiveProjectId(projectId);

  // Check if file exists
  if (!fs.existsSync(filePath)) {
    throw new Error(`File not found: ${filePath}`);
  }

  // Read the file
  const fileBuffer = fs.readFileSync(filePath);
  const fileName = path.basename(filePath);

  // Create form data
  const FormData = (await import("form-data")).default;
  const form = new FormData();
  form.append("file", fileBuffer, {
    filename: fileName,
    contentType: "application/octet-stream",
  });

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/uploads`
  );

  const defaultFetchConfig = getFetchConfig();
  delete defaultFetchConfig.headers["Content-Type"]; // Let form-data set the correct Content-Type with boundary

  const response = await fetch(url.toString(), {
    ...defaultFetchConfig,
    method: "POST",
    body: form
  });

  if (!response.ok) {
    await handleGitLabError(response);
  }

  const data = await response.json();
  return GitLabMarkdownUploadSchema.parse(data);
}

const IMAGE_MIME_TYPES: Record<string, string> = {
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".jpeg": "image/jpeg",
  ".gif": "image/gif",
  ".webp": "image/webp",
  ".svg": "image/svg+xml",
  ".bmp": "image/bmp",
  ".ico": "image/x-icon",
};

function getImageMimeType(filename: string): string | null {
  const ext = path.extname(filename).toLowerCase();
  return IMAGE_MIME_TYPES[ext] ?? null;
}

interface DownloadAttachmentResult {
  buffer: Buffer;
  filename: string;
  mimeType: string | null;
  savedPath?: string;
}

async function downloadAttachment(
  projectId: string,
  secret: string,
  filename: string,
  localPath?: string
): Promise<DownloadAttachmentResult> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/uploads/${secret}/${filename}`
  );

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
    method: "GET",
  });

  if (!response.ok) {
    await handleGitLabError(response);
  }

  // Get the file content as buffer
  const buffer = Buffer.from(await response.arrayBuffer());
  const mimeType = getImageMimeType(filename);

  // For non-image files, always save to disk.
  // For image files, only save to disk if local_path is explicitly provided.
  if (!mimeType || localPath) {
    let savePath: string;
    if (localPath) {
      const normalizedLocalPath = path.normalize(localPath);
      if (
        path.isAbsolute(normalizedLocalPath) ||
        normalizedLocalPath === ".." ||
        normalizedLocalPath.startsWith(".." + path.sep) ||
        normalizedLocalPath.includes(path.sep + ".." + path.sep)
      ) {
        throw new Error("Invalid local_path: directory traversal is not allowed.");
      }
      savePath = path.join(normalizedLocalPath, filename);
    } else {
      savePath = filename;
    }
    const dir = path.dirname(savePath);
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true });
    }
    fs.writeFileSync(savePath, buffer);
    return { buffer, filename, mimeType, savedPath: savePath };
  }

  return { buffer, filename, mimeType };
}

/**
 * List all events for the currently authenticated user
 * @param {Object} options - Options for listing events
 * @returns {Promise<GitLabEvent[]>} List of events
 */
async function listEvents(options: z.infer<typeof ListEventsSchema> = {}): Promise<GitLabEvent[]> {
  const url = new URL(`${getEffectiveApiUrl()}/events`);

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), { ...getFetchConfig() });

  if (!response.ok) {
    await handleGitLabError(response);
  }

  const data = await response.json();
  return GitLabEventSchema.array().parse(data);
}

/**
 * List all visible events for a specified project
 * @param {string} projectId - Project ID or URL-encoded path
 * @param {Object} options - Options for getting project events
 * @returns {Promise<GitLabEvent[]>} List of project events
 */
async function getProjectEvents(
  projectId: string,
  options: Omit<z.infer<typeof GetProjectEventsSchema>, "project_id"> = {}
): Promise<GitLabEvent[]> {
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/events`
  );

  // Add all query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), { ...getFetchConfig() });

  if (!response.ok) {
    await handleGitLabError(response);
  }

  const data = await response.json();
  return GitLabEventSchema.array().parse(data);
}

/**
 * List all releases for a project
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param options Optional parameters for listing releases
 * @returns Array of GitLab releases
 */
async function listReleases(
  projectId: string,
  options: Omit<z.infer<typeof ListReleasesSchema>, "project_id"> = {}
): Promise<GitLabRelease[]> {
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases`
  );

  // Add query parameters
  Object.entries(options).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.append(key, value.toString());
    }
  });

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabReleaseSchema.array().parse(data);
}

/**
 * Get a release by tag name
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param tagName The Git tag the release is associated with
 * @param includeHtmlDescription If true, includes HTML rendered Markdown
 * @returns GitLab release
 */
async function getRelease(
  projectId: string,
  tagName: string,
  includeHtmlDescription?: boolean
): Promise<GitLabRelease> {
  const effectiveProjectId = getEffectiveProjectId(projectId);
  const url = new URL(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tagName)}`
  );

  if (includeHtmlDescription !== undefined) {
    url.searchParams.append("include_html_description", includeHtmlDescription.toString());
  }

  const response = await fetch(url.toString(), {
    ...getFetchConfig(),
  });

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabReleaseSchema.parse(data);
}

/**
 * Create a new release
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param options Options for creating the release
 * @returns Created GitLab release
 */
async function createRelease(
  projectId: string,
  options: Omit<z.infer<typeof CreateReleaseSchema>, "project_id">
): Promise<GitLabRelease> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases`,
    {
      ...getFetchConfig(),
      method: "POST",
      body: JSON.stringify(options),
    }
  );

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabReleaseSchema.parse(data);
}

/**
 * Update an existing release
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param tagName The Git tag the release is associated with
 * @param options Options for updating the release
 * @returns Updated GitLab release
 */
async function updateRelease(
  projectId: string,
  tagName: string,
  options: Omit<z.infer<typeof UpdateReleaseSchema>, "project_id" | "tag_name">
): Promise<GitLabRelease> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tagName)}`,
    {
      ...getFetchConfig(),
      method: "PUT",
      body: JSON.stringify(options),
    }
  );

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabReleaseSchema.parse(data);
}

/**
 * Delete a release
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param tagName The Git tag the release is associated with
 * @returns Deleted GitLab release
 */
async function deleteRelease(projectId: string, tagName: string): Promise<GitLabRelease> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tagName)}`,
    {
      ...getFetchConfig(),
      method: "DELETE",
    }
  );

  await handleGitLabError(response);

  const data = await response.json();
  return GitLabReleaseSchema.parse(data);
}

/**
 * Create release evidence (GitLab Premium/Ultimate only)
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param tagName The Git tag the release is associated with
 */
async function createReleaseEvidence(projectId: string, tagName: string): Promise<void> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tagName)}/evidence`,
    {
      ...getFetchConfig(),
      method: "POST",
    }
  );

  await handleGitLabError(response);
}

/**
 * Download a release asset
 *
 * @param projectId The ID or URL-encoded path of the project
 * @param tagName The Git tag the release is associated with
 * @param directAssetPath Path to the release asset file
 * @returns The asset file content
 */
async function downloadReleaseAsset(
  projectId: string,
  tagName: string,
  directAssetPath: string
): Promise<string> {
  const effectiveProjectId = getEffectiveProjectId(projectId);

  const response = await fetch(
    `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/releases/${encodeURIComponent(tagName)}/downloads/${directAssetPath}`,
    {
      ...getFetchConfig(),
    }
  );

  await handleGitLabError(response);

  return await response.text();
}

// Request handlers are now registered inside createServer() factory function
// to ensure each transport connection gets its own Server instance (GHSA-345p-7cg4-v4c7).

async function handleToolCall(params: any) {
  try {
    if (!params.arguments) {
      throw new Error("Arguments are required");
    }

    // Ensure session is established for every request if cookie authentication is enabled
    if (GITLAB_AUTH_COOKIE_PATH) {
      await ensureSessionForRequest();
    }

    // Lazy OAuth token refresh: only validate/refresh when a tool is actually called
    await ensureValidOAuthToken();

    // Normalize common parameter aliases that LLMs send
    const args = params.arguments as Record<string, unknown>;
    if (args) {
      // work_item_iid -> iid (for work item tools)
      if (args.work_item_iid !== undefined && args.iid === undefined) {
        args.iid = args.work_item_iid;
        delete args.work_item_iid;
      }
    }

    logger.info({ tool: params.name, event: "tool_call_start" }, `tool_call_start: ${params.name}`);
    switch (params.name) {
      case "execute_graphql": {
        const args = ExecuteGraphQLSchema.parse(params.arguments);
        const apiUrl = new URL(getEffectiveApiUrl());
        // Build GraphQL endpoint preserving any instance subpath (e.g. /gitlab)
        const restPath = apiUrl.pathname || ""; // e.g. /api/v4 or /gitlab/api/v4
        const idx = restPath.lastIndexOf("/api/v4");
        const prefix = idx >= 0 ? restPath.slice(0, idx) : "";
        const graphqlUrl =
          process.env.GITLAB_GRAPHQL_URL || `${apiUrl.origin}${prefix}/api/graphql`;

        // Add timeout to avoid hanging requests
        const controller = new AbortController();
        const timeoutMs = 45000;
        const timeout = setTimeout(() => controller.abort(), timeoutMs);
        logger.info({ endpoint: graphqlUrl }, "execute_graphql request");
        try {
          const response = await fetch(graphqlUrl, {
            ...getFetchConfig(),
            method: "POST",
            headers: {
              ...BASE_HEADERS,
              ...buildAuthHeaders(),
            },
            body: JSON.stringify({ query: args.query, variables: args.variables || {} }),
            signal: controller.signal as any,
          });
          if (!response.ok) {
            await handleGitLabError(response);
          }
          const json = await response.json();
          return {
            content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
          };
        } catch (err) {
          const message = err instanceof Error ? err.message : String(err);
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({ error: `GraphQL request failed: ${message}` }, null, 2),
              },
            ],
          };
        } finally {
          clearTimeout(timeout);
        }
      }
      case "fork_repository": {
        if (GITLAB_PROJECT_ID) {
          throw new Error("Direct project ID is set. So fork_repository is not allowed");
        }
        const forkArgs = ForkRepositorySchema.parse(params.arguments);
        try {
          const forkedProject = await forkProject(forkArgs.project_id, forkArgs.namespace);
          return {
            content: [{ type: "text", text: JSON.stringify(forkedProject, null, 2) }],
          };
        } catch (forkError) {
          logger.error("Error forking repository:", forkError);
          let forkErrorMessage = "Failed to fork repository";
          if (forkError instanceof Error) {
            forkErrorMessage = `${forkErrorMessage}: ${forkError.message}`;
          }
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({ error: forkErrorMessage }, null, 2),
              },
            ],
          };
        }
      }

      case "create_branch": {
        const args = CreateBranchSchema.parse(params.arguments);
        let ref = args.ref;
        if (!ref) {
          ref = await getDefaultBranchRef(args.project_id);
        }

        const branch = await createBranch(args.project_id, {
          name: args.branch,
          ref,
        });

        return {
          content: [{ type: "text", text: JSON.stringify(branch, null, 2) }],
        };
      }

      case "get_branch_diffs": {
        const args = GetBranchDiffsSchema.parse(params.arguments);
        const diffResp = await getBranchDiffs(args.project_id, args.from, args.to, args.straight);
        diffResp.diffs = filterDiffsByPatterns(diffResp.diffs, args.excluded_file_patterns);
        return {
          content: [{ type: "text", text: JSON.stringify(diffResp, null, 2) }],
        };
      }

      case "search_repositories": {
        const args = SearchRepositoriesSchema.parse(params.arguments);
        const results = await searchProjects(args.search, args.page, args.per_page);
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      }

      case "search_code": {
        const args = SearchCodeSchema.parse(params.arguments);
        const results = await searchBlobs({
          search: args.search,
          filename: args.filename,
          path: args.path,
          extension: args.extension,
          page: args.page,
          per_page: args.per_page,
        });
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      }

      case "search_project_code": {
        const args = SearchProjectCodeSchema.parse(params.arguments);
        const results = await searchBlobs({
          search: args.search,
          project_id: args.project_id,
          ref: args.ref,
          filename: args.filename,
          path: args.path,
          extension: args.extension,
          page: args.page,
          per_page: args.per_page,
        });
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      }

      case "search_group_code": {
        const args = SearchGroupCodeSchema.parse(params.arguments);
        const results = await searchBlobs({
          search: args.search,
          group_id: args.group_id,
          filename: args.filename,
          path: args.path,
          extension: args.extension,
          page: args.page,
          per_page: args.per_page,
        });
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      }

      case "create_repository": {
        if (GITLAB_PROJECT_ID) {
          throw new Error("Direct project ID is set. So fork_repository is not allowed");
        }
        const args = CreateRepositorySchema.parse(params.arguments);
        const repository = await createRepository(args);
        return {
          content: [{ type: "text", text: JSON.stringify(repository, null, 2) }],
        };
      }

      case "get_file_contents": {
        const args = GetFileContentsSchema.parse(params.arguments);
        const contents = await getFileContents(args.project_id, args.file_path, args.ref);
        return {
          content: [{ type: "text", text: JSON.stringify(contents, null, 2) }],
        };
      }

      case "create_or_update_file": {
        const args = CreateOrUpdateFileSchema.parse(params.arguments);
        const result = await createOrUpdateFile(
          args.project_id,
          args.file_path,
          args.content,
          args.commit_message,
          args.branch,
          args.previous_path,
          args.last_commit_id,
          args.commit_id
        );
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "push_files": {
        const args = PushFilesSchema.parse(params.arguments);
        const result = await createCommit(
          args.project_id,
          args.commit_message,
          args.branch,
          args.files.map(f => ({ path: f.file_path, content: f.content }))
        );
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "create_issue": {
        const args = CreateIssueSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const issue = await createIssue(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(issue, null, 2) }],
        };
      }

      case "create_merge_request": {
        const args = CreateMergeRequestSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const mergeRequest = await createMergeRequest(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(mergeRequest, null, 2) }],
        };
      }

      case "delete_merge_request_discussion_note": {
        const args = DeleteMergeRequestDiscussionNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, discussion_id, note_id } = args;
        await deleteMergeRequestDiscussionNote(
          project_id,
          merge_request_iid,
          discussion_id,
          note_id
        );

        return {
          content: [{ type: "text", text: "Merge request discussion note deleted successfully" }],
        };
      }

      case "update_merge_request_discussion_note": {
        const args = UpdateMergeRequestDiscussionNoteSchema.parse(params.arguments);
        const note = await updateMergeRequestDiscussionNote(
          args.project_id,
          args.merge_request_iid,
          args.discussion_id,
          args.note_id,
          args.body, // Now optional
          args.resolved // Now one of body or resolved must be provided, not both
        );
        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "create_merge_request_discussion_note": {
        const args = CreateMergeRequestDiscussionNoteSchema.parse(params.arguments);
        const note = await createMergeRequestDiscussionNote(
          args.project_id,
          args.merge_request_iid,
          args.discussion_id,
          args.body,
          args.created_at
        );
        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "create_merge_request_note": {
        const args = CreateMergeRequestNoteSchema.parse(params.arguments);
        const note = await createMergeRequestNote(
          args.project_id,
          args.merge_request_iid,
          args.body
        );

        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "delete_merge_request_note": {
        const args = DeleteMergeRequestNoteSchema.parse(params.arguments);
        await deleteMergeRequestNote(args.project_id, args.merge_request_iid, args.note_id);

        return {
          content: [{ type: "text", text: "Merge request note deleted successfully" }],
        };
      }

      case "get_merge_request_note": {
        const args = GetMergeRequestNoteSchema.parse(params.arguments);
        const note = await getMergeRequestNote(
          args.project_id,
          args.merge_request_iid,
          args.note_id
        );

        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "get_merge_request_notes": {
        const args = GetMergeRequestNotesSchema.parse(params.arguments);
        const notes = await getMergeRequestNotes(
          args.project_id,
          args.merge_request_iid,
          args.sort,
          args.order_by,
          args.per_page,
          args.page
        );

        return {
          content: [{ type: "text", text: JSON.stringify(notes, null, 2) }],
        };
      }

      case "update_merge_request_note": {
        const args = UpdateMergeRequestNoteSchema.parse(params.arguments);
        const note = await updateMergeRequestNote(
          args.project_id,
          args.merge_request_iid,
          args.note_id,
          args.body
        );

        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "update_issue_note": {
        const args = UpdateIssueNoteSchema.parse(params.arguments);
        const note = await updateIssueNote(
          args.project_id,
          args.issue_iid,
          args.discussion_id,
          args.note_id,
          args.body,
          args.resolved
        );
        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "create_issue_note": {
        const args = CreateIssueNoteSchema.parse(params.arguments);
        const note = await createIssueNote(
          args.project_id,
          args.issue_iid,
          args.discussion_id,
          args.body,
          args.created_at
        );
        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "get_merge_request": {
        const args = GetMergeRequestSchema.parse(params.arguments);
        const mergeRequest = await getMergeRequest(
          args.project_id,
          args.merge_request_iid,
          args.source_branch
        );
        const deploymentSummary = await buildMergeRequestDeploymentSummary(
          args.project_id,
          mergeRequest
        );
        const commitAdditionSummary = await buildMergeRequestCommitAdditionSummary(
          args.project_id,
          mergeRequest
        );
        const approvalSummary = await buildMergeRequestApprovalSummary(
          args.project_id,
          mergeRequest.iid
        );
        const mergeRequestWithDeploymentSummary: GitLabMergeRequestWithDeploymentSummary = {
          ...mergeRequest,
          deployment_summary: deploymentSummary,
          commit_addition_summary: commitAdditionSummary,
          approval_summary: approvalSummary,
        };
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(mergeRequestWithDeploymentSummary, null, 2),
            },
          ],
        };
      }

      case "get_merge_request_diffs": {
        const args = GetMergeRequestDiffsSchema.parse(params.arguments);
        const diffs = await getMergeRequestDiffs(
          args.project_id,
          args.merge_request_iid,
          args.source_branch,
          args.view
        );
        const filteredDiffs = filterDiffsByPatterns(diffs, args.excluded_file_patterns);
        return {
          content: [{ type: "text", text: JSON.stringify(filteredDiffs, null, 2) }],
        };
      }

      case "list_merge_request_changed_files": {
        const args = ListMergeRequestChangedFilesSchema.parse(params.arguments);
        const files = await listMergeRequestChangedFiles(
          args.project_id,
          args.merge_request_iid,
          args.source_branch,
          args.excluded_file_patterns
        );
        return {
          content: [{ type: "text", text: JSON.stringify(files, null, 2) }],
        };
      }

      case "list_merge_request_diffs": {
        const args = ListMergeRequestDiffsSchema.parse(params.arguments);
        const changes = await listMergeRequestDiffs(
          args.project_id,
          args.merge_request_iid,
          args.source_branch,
          args.page,
          args.per_page,
          args.unidiff
        );
        return {
          content: [{ type: "text", text: JSON.stringify(changes, null, 2) }],
        };
      }

      case "get_merge_request_file_diff": {
        const args = GetMergeRequestFileDiffSchema.parse(params.arguments);
        const fileDiff = await getMergeRequestFileDiff(
          args.project_id,
          args.file_paths,
          args.merge_request_iid,
          args.source_branch,
          args.unidiff
        );
        return {
          content: [{ type: "text", text: JSON.stringify(fileDiff, null, 2) }],
        };
      }

      case "list_merge_request_versions": {
        const args = ListMergeRequestVersionsSchema.parse(params.arguments);
        const versions = await listMergeRequestVersions(args.project_id, args.merge_request_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(versions, null, 2) }],
        };
      }

      case "get_merge_request_version": {
        const args = GetMergeRequestVersionSchema.parse(params.arguments);
        const version = await getMergeRequestVersion(
          args.project_id,
          args.merge_request_iid,
          args.version_id,
          args.unidiff
        );
        return {
          content: [{ type: "text", text: JSON.stringify(version, null, 2) }],
        };
      }

      case "update_merge_request": {
        const args = UpdateMergeRequestSchema.parse(params.arguments);
        const { project_id, merge_request_iid, source_branch, ...options } = args;
        const mergeRequest = await updateMergeRequest(
          project_id,
          options,
          merge_request_iid,
          source_branch
        );
        return {
          content: [{ type: "text", text: JSON.stringify(mergeRequest, null, 2) }],
        };
      }

      case "merge_merge_request": {
        const args = MergeMergeRequestSchema.parse(params.arguments);
        const { project_id, merge_request_iid, ...options } = args;
        const mergeRequest = await mergeMergeRequest(project_id, options, merge_request_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(mergeRequest, null, 2) }],
        };
      }

      case "approve_merge_request": {
        const args = ApproveMergeRequestSchema.parse(params.arguments);
        const approvalState = await approveMergeRequest(
          args.project_id,
          args.merge_request_iid,
          args.sha,
          args.approval_password
        );
        return {
          content: [{ type: "text", text: JSON.stringify(approvalState, null, 2) }],
        };
      }

      case "unapprove_merge_request": {
        const args = UnapproveMergeRequestSchema.parse(params.arguments);
        const approvalState = await unapproveMergeRequest(args.project_id, args.merge_request_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(approvalState, null, 2) }],
        };
      }

      case "get_merge_request_approval_state": {
        const args = GetMergeRequestApprovalStateSchema.parse(params.arguments);
        const approvalState = await getMergeRequestApprovalState(
          args.project_id,
          args.merge_request_iid
        );
        return {
          content: [{ type: "text", text: JSON.stringify(approvalState, null, 2) }],
        };
      }

      case "get_merge_request_conflicts": {
        const args = GetMergeRequestConflictsSchema.parse(params.arguments);
        const conflicts = await getMergeRequestConflicts(
          args.project_id,
          args.merge_request_iid
        );
        return {
          content: [{ type: "text", text: JSON.stringify(conflicts, null, 2) }],
        };
      }

      case "mr_discussions": {
        const args = ListMergeRequestDiscussionsSchema.parse(params.arguments);
        const { project_id, merge_request_iid, ...options } = args;
        const discussions = await listMergeRequestDiscussions(
          project_id,
          merge_request_iid,
          options
        );
        return {
          content: [{ type: "text", text: JSON.stringify(discussions, null, 2) }],
        };
      }

      case "list_namespaces": {
        const args = ListNamespacesSchema.parse(params.arguments);
        const url = new URL(`${GITLAB_API_URL}/namespaces`);

        if (args.search) {
          url.searchParams.append("search", args.search);
        }
        if (args.page) {
          url.searchParams.append("page", args.page.toString());
        }
        if (args.per_page) {
          url.searchParams.append("per_page", args.per_page.toString());
        }
        if (args.owned) {
          url.searchParams.append("owned", args.owned.toString());
        }

        const response = await fetch(url.toString(), {
          ...getFetchConfig(),
        });

        await handleGitLabError(response);
        const data = await response.json();
        const namespaces = z.array(GitLabNamespaceSchema).parse(data);

        return {
          content: [{ type: "text", text: JSON.stringify(namespaces, null, 2) }],
        };
      }

      case "get_namespace": {
        const args = GetNamespaceSchema.parse(params.arguments);
        const url = new URL(
          `${GITLAB_API_URL}/namespaces/${encodeURIComponent(args.namespace_id)}`
        );

        const response = await fetch(url.toString(), {
          ...getFetchConfig(),
        });

        await handleGitLabError(response);
        const data = await response.json();
        const namespace = GitLabNamespaceSchema.parse(data);

        return {
          content: [{ type: "text", text: JSON.stringify(namespace, null, 2) }],
        };
      }

      case "verify_namespace": {
        const args = VerifyNamespaceSchema.parse(params.arguments);
        const url = new URL(`${GITLAB_API_URL}/namespaces/${encodeURIComponent(args.path)}/exists`);

        const response = await fetch(url.toString(), {
          ...getFetchConfig(),
        });

        await handleGitLabError(response);
        const data = await response.json();
        const namespaceExists = GitLabNamespaceExistsResponseSchema.parse(data);

        return {
          content: [{ type: "text", text: JSON.stringify(namespaceExists, null, 2) }],
        };
      }

      case "get_project": {
        const args = GetProjectSchema.parse(params.arguments);
        const options = params.arguments as {
          license?: boolean;
          statistics?: boolean;
          with_custom_attributes?: boolean;
        };
        const effectiveProjectId = getEffectiveProjectId(args.project_id);
        const url = new URL(
          `${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}`
        );

        if (options.license) url.searchParams.append("license", "true");
        if (options.statistics) url.searchParams.append("statistics", "true");
        if (options.with_custom_attributes)
          url.searchParams.append("with_custom_attributes", "true");

        const response = await fetch(url.toString(), {
          ...getFetchConfig(),
        });

        await handleGitLabError(response);
        const data = await response.json();
        // Return raw data without parsing through our schema to avoid type mismatches in tests
        return {
          content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
        };
      }

      case "list_projects": {
        const args = ListProjectsSchema.parse(params.arguments);
        const projects = await listProjects(args);

        return {
          content: [{ type: "text", text: JSON.stringify(projects, null, 2) }],
        };
      }

      case "list_project_members": {
        const args = ListProjectMembersSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const members = await listProjectMembers(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(members, null, 2) }],
        };
      }

      case "get_users": {
        const args = GetUsersSchema.parse(params.arguments);
        const usersMap = await getUsers(args.usernames);

        return {
          content: [{ type: "text", text: JSON.stringify(usersMap, null, 2) }],
        };
      }

      case "create_note": {
        const args = CreateNoteSchema.parse(params.arguments);
        const { project_id, noteable_type, noteable_iid, body } = args;

        const note = await createNote(project_id, noteable_type, noteable_iid, body);
        return {
          content: [{ type: "text", text: JSON.stringify(note, null, 2) }],
        };
      }

      case "get_draft_note": {
        const args = GetDraftNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, draft_note_id } = args;

        const draftNote = await getDraftNote(project_id, merge_request_iid, draft_note_id);
        return {
          content: [{ type: "text", text: JSON.stringify(draftNote, null, 2) }],
        };
      }

      case "list_draft_notes": {
        const args = ListDraftNotesSchema.parse(params.arguments);
        const { project_id, merge_request_iid } = args;

        const draftNotes = await listDraftNotes(project_id, merge_request_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(draftNotes, null, 2) }],
        };
      }

      case "create_draft_note": {
        const args = CreateDraftNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, body, in_reply_to_discussion_id, position, resolve_discussion } = args;

        const draftNote = await createDraftNote(
          project_id,
          merge_request_iid,
          body,
          in_reply_to_discussion_id,
          position,
          resolve_discussion
        );
        return {
          content: [{ type: "text", text: JSON.stringify(draftNote, null, 2) }],
        };
      }

      case "update_draft_note": {
        const args = UpdateDraftNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, draft_note_id, body, position, resolve_discussion } =
          args;

        const draftNote = await updateDraftNote(
          project_id,
          merge_request_iid,
          draft_note_id,
          body,
          position,
          resolve_discussion
        );
        return {
          content: [{ type: "text", text: JSON.stringify(draftNote, null, 2) }],
        };
      }

      case "delete_draft_note": {
        const args = DeleteDraftNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, draft_note_id } = args;

        await deleteDraftNote(project_id, merge_request_iid, draft_note_id);
        return {
          content: [{ type: "text", text: "Draft note deleted successfully" }],
        };
      }

      case "publish_draft_note": {
        const args = PublishDraftNoteSchema.parse(params.arguments);
        const { project_id, merge_request_iid, draft_note_id } = args;

        const publishedNote = await publishDraftNote(project_id, merge_request_iid, draft_note_id);
        return {
          content: [{ type: "text", text: JSON.stringify(publishedNote, null, 2) }],
        };
      }

      case "bulk_publish_draft_notes": {
        const args = BulkPublishDraftNotesSchema.parse(params.arguments);
        const { project_id, merge_request_iid } = args;

        const publishedNotes = await bulkPublishDraftNotes(project_id, merge_request_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(publishedNotes, null, 2) }],
        };
      }

      case "create_merge_request_thread": {
        const args = CreateMergeRequestThreadSchema.parse(params.arguments);
        const { project_id, merge_request_iid, body, position, created_at } = args;

        const thread = await createMergeRequestThread(
          project_id,
          merge_request_iid,
          body,
          position,
          created_at
        );
        return {
          content: [{ type: "text", text: JSON.stringify(thread, null, 2) }],
        };
      }

      case "resolve_merge_request_thread": {
        const args = ResolveMergeRequestThreadSchema.parse(params.arguments);
        const { project_id, merge_request_iid, discussion_id, resolved } = args;
        await resolveMergeRequestThread(project_id, merge_request_iid, discussion_id, resolved);
        return {
          content: [{ type: "text", text: "Thread resolved successfully" }],
        };
      }

      case "list_issues": {
        const args = ListIssuesSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const issues = await listIssues(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(issues, null, 2) }],
        };
      }

      case "my_issues": {
        const args = MyIssuesSchema.parse(params.arguments);
        const issues = await myIssues(args);
        return {
          content: [{ type: "text", text: JSON.stringify(issues, null, 2) }],
        };
      }

      case "get_issue": {
        const args = GetIssueSchema.parse(params.arguments);
        const issue = await getIssue(args.project_id, args.issue_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(issue, null, 2) }],
        };
      }

      case "update_issue": {
        const args = UpdateIssueSchema.parse(params.arguments);
        const { project_id, issue_iid, ...options } = args;
        const issue = await updateIssue(project_id, issue_iid, options);
        return {
          content: [{ type: "text", text: JSON.stringify(issue, null, 2) }],
        };
      }

      case "delete_issue": {
        const args = DeleteIssueSchema.parse(params.arguments);
        await deleteIssue(args.project_id, args.issue_iid);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                { status: "success", message: "Issue deleted successfully" },
                null,
                2
              ),
            },
          ],
        };
      }

      case "list_issue_links": {
        const args = ListIssueLinksSchema.parse(params.arguments);
        const links = await listIssueLinks(args.project_id, args.issue_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(links, null, 2) }],
        };
      }

      case "list_issue_discussions": {
        const args = ListIssueDiscussionsSchema.parse(params.arguments);
        const { project_id, issue_iid, ...options } = args;

        const discussions = await listIssueDiscussions(project_id, issue_iid, options);
        return {
          content: [{ type: "text", text: JSON.stringify(discussions, null, 2) }],
        };
      }

      case "get_issue_link": {
        const args = GetIssueLinkSchema.parse(params.arguments);
        const link = await getIssueLink(args.project_id, args.issue_iid, args.issue_link_id);
        return {
          content: [{ type: "text", text: JSON.stringify(link, null, 2) }],
        };
      }

      case "create_issue_link": {
        const args = CreateIssueLinkSchema.parse(params.arguments);
        const link = await createIssueLink(
          args.project_id,
          args.issue_iid,
          args.target_project_id,
          args.target_issue_iid,
          args.link_type
        );
        return {
          content: [{ type: "text", text: JSON.stringify(link, null, 2) }],
        };
      }

      case "delete_issue_link": {
        const args = DeleteIssueLinkSchema.parse(params.arguments);
        await deleteIssueLink(args.project_id, args.issue_iid, args.issue_link_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  status: "success",
                  message: "Issue link deleted successfully",
                },
                null,
                2
              ),
            },
          ],
        };
      }

      case "get_work_item": {
        const args = GetWorkItemSchema.parse(params.arguments);
        const result = await getWorkItem(args.project_id, args.iid);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "list_work_items": {
        const args = ListWorkItemsSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const result = await listWorkItems(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "create_work_item": {
        const args = CreateWorkItemSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const result = await createWorkItem(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "update_work_item": {
        const args = UpdateWorkItemSchema.parse(params.arguments);
        const { project_id, iid, ...options } = args;
        const result = await updateWorkItem(project_id, iid, options);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "convert_work_item_type": {
        const args = ConvertWorkItemTypeSchema.parse(params.arguments);
        const result = await convertIssueType(
          args.project_id,
          args.iid,
          args.new_type
        );
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "list_work_item_statuses": {
        const args = ListWorkItemStatusesSchema.parse(params.arguments);
        const result = await listIssueStatuses(args.project_id, args.work_item_type);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "list_custom_field_definitions": {
        const args = ListCustomFieldDefinitionsSchema.parse(params.arguments);
        const result = await listCustomFieldDefinitions(args.project_id, args.work_item_type);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "move_work_item": {
        const args = MoveWorkItemSchema.parse(params.arguments);
        const result = await moveWorkItem(args.project_id, args.iid, args.target_project_id);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "list_work_item_notes": {
        const args = ListWorkItemNotesSchema.parse(params.arguments);
        const result = await listWorkItemNotes(args.project_id, args.iid, args);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "create_work_item_note": {
        const args = CreateWorkItemNoteSchema.parse(params.arguments);
        const result = await createWorkItemNote(args.project_id, args.iid, args.body, args);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "get_timeline_events": {
        const args = GetTimelineEventsSchema.parse(params.arguments);
        const result = await getTimelineEvents(args.project_id, args.incident_iid);
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "create_timeline_event": {
        const args = CreateTimelineEventSchema.parse(params.arguments);
        const result = await createTimelineEvent(
          args.project_id,
          args.incident_iid,
          args.note,
          args.occurred_at,
          args.tag_names
        );
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      }

      case "list_labels": {
        const args = ListLabelsSchema.parse(params.arguments);
        const labels = await listLabels(args.project_id, args);
        return {
          content: [{ type: "text", text: JSON.stringify(labels, null, 2) }],
        };
      }

      case "get_label": {
        const args = GetLabelSchema.parse(params.arguments);
        const label = await getLabel(args.project_id, args.label_id, args.include_ancestor_groups);
        return {
          content: [{ type: "text", text: JSON.stringify(label, null, 2) }],
        };
      }

      case "create_label": {
        const args = CreateLabelSchema.parse(params.arguments);
        const label = await createLabel(args.project_id, args);
        return {
          content: [{ type: "text", text: JSON.stringify(label, null, 2) }],
        };
      }

      case "update_label": {
        const args = UpdateLabelSchema.parse(params.arguments);
        const { project_id, label_id, ...options } = args;
        const label = await updateLabel(project_id, label_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(label, null, 2) }],
        };
      }

      case "delete_label": {
        const args = DeleteLabelSchema.parse(params.arguments);
        await deleteLabel(args.project_id, args.label_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                { status: "success", message: "Label deleted successfully" },
                null,
                2
              ),
            },
          ],
        };
      }

      case "list_group_projects": {
        const args = ListGroupProjectsSchema.parse(params.arguments);
        const projects = await listGroupProjects(args);
        return {
          content: [{ type: "text", text: JSON.stringify(projects, null, 2) }],
        };
      }

      case "list_wiki_pages": {
        const { project_id, page, per_page, with_content } = ListWikiPagesSchema.parse(
          params.arguments
        );
        const wikiPages = await listWikiPages(project_id, {
          page,
          per_page,
          with_content,
        });
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPages, null, 2) }],
        };
      }

      case "get_wiki_page": {
        const { project_id, slug } = GetWikiPageSchema.parse(params.arguments);
        const wikiPage = await getWikiPage(project_id, slug);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "create_wiki_page": {
        const { project_id, title, content, format } = CreateWikiPageSchema.parse(params.arguments);
        const wikiPage = await createWikiPage(project_id, title, content, format);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "update_wiki_page": {
        const { project_id, slug, title, content, format } = UpdateWikiPageSchema.parse(
          params.arguments
        );
        const wikiPage = await updateWikiPage(project_id, slug, title, content, format);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "delete_wiki_page": {
        const { project_id, slug } = DeleteWikiPageSchema.parse(params.arguments);
        await deleteWikiPage(project_id, slug);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  status: "success",
                  message: "Wiki page deleted successfully",
                },
                null,
                2
              ),
            },
          ],
        };
      }

      case "list_group_wiki_pages": {
        const { group_id, page, per_page, with_content } = ListGroupWikiPagesSchema.parse(
          params.arguments
        );
        const wikiPages = await listGroupWikiPages(group_id, {
          page,
          per_page,
          with_content,
        });
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPages, null, 2) }],
        };
      }

      case "get_group_wiki_page": {
        const { group_id, slug } = GetGroupWikiPageSchema.parse(params.arguments);
        const wikiPage = await getGroupWikiPage(group_id, slug);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "create_group_wiki_page": {
        const { group_id, title, content, format } = CreateGroupWikiPageSchema.parse(
          params.arguments
        );
        const wikiPage = await createGroupWikiPage(group_id, title, content, format);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "update_group_wiki_page": {
        const { group_id, slug, title, content, format } = UpdateGroupWikiPageSchema.parse(
          params.arguments
        );
        const wikiPage = await updateGroupWikiPage(group_id, slug, title, content, format);
        return {
          content: [{ type: "text", text: JSON.stringify(wikiPage, null, 2) }],
        };
      }

      case "delete_group_wiki_page": {
        const { group_id, slug } = DeleteGroupWikiPageSchema.parse(params.arguments);
        await deleteGroupWikiPage(group_id, slug);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  status: "success",
                  message: "Group wiki page deleted successfully",
                },
                null,
                2
              ),
            },
          ],
        };
      }

      case "get_repository_tree": {
        const args = GetRepositoryTreeSchema.parse(params.arguments);
        const tree = await getRepositoryTree(args);
        return {
          content: [{ type: "text", text: JSON.stringify(tree, null, 2) }],
        };
      }

      case "list_pipelines": {
        const args = ListPipelinesSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const pipelines = await listPipelines(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(pipelines, null, 2) }],
        };
      }

      case "get_pipeline": {
        const { project_id, pipeline_id } = GetPipelineSchema.parse(params.arguments);
        const pipeline = await getPipeline(project_id, pipeline_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(pipeline, null, 2),
            },
          ],
        };
      }

      case "list_deployments": {
        const args = ListDeploymentsSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const deployments = await listDeployments(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(deployments, null, 2) }],
        };
      }

      case "get_deployment": {
        const { project_id, deployment_id } = GetDeploymentSchema.parse(params.arguments);
        const deployment = await getDeployment(project_id, deployment_id);
        return {
          content: [{ type: "text", text: JSON.stringify(deployment, null, 2) }],
        };
      }

      case "list_environments": {
        const args = ListEnvironmentsSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const environments = await listEnvironments(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(environments, null, 2) }],
        };
      }

      case "get_environment": {
        const { project_id, environment_id } = GetEnvironmentSchema.parse(params.arguments);
        const environment = await getEnvironment(project_id, environment_id);
        return {
          content: [{ type: "text", text: JSON.stringify(environment, null, 2) }],
        };
      }

      case "list_pipeline_jobs": {
        const { project_id, pipeline_id, ...options } = ListPipelineJobsSchema.parse(
          params.arguments
        );
        const jobs = await listPipelineJobs(project_id, pipeline_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(jobs, null, 2),
            },
          ],
        };
      }

      case "list_pipeline_trigger_jobs": {
        const { project_id, pipeline_id, ...options } = ListPipelineTriggerJobsSchema.parse(
          params.arguments
        );
        const triggerJobs = await listPipelineTriggerJobs(project_id, pipeline_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(triggerJobs, null, 2),
            },
          ],
        };
      }

      case "get_pipeline_job": {
        const { project_id, job_id } = GetPipelineJobOutputSchema.parse(params.arguments);
        const jobDetails = await getPipelineJob(project_id, job_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(jobDetails, null, 2),
            },
          ],
        };
      }

      case "get_pipeline_job_output": {
        const { project_id, job_id, limit, offset } = GetPipelineJobOutputSchema.parse(
          params.arguments
        );
        const jobOutput = await getPipelineJobOutput(project_id, job_id, limit, offset);
        return {
          content: [
            {
              type: "text",
              text: jobOutput,
            },
          ],
        };
      }

      case "create_pipeline": {
        const { project_id, ref, variables, inputs } = CreatePipelineSchema.parse(params.arguments);
        const pipeline = await createPipeline(project_id, ref, variables, inputs);
        return {
          content: [
            {
              type: "text",
              text: `Created pipeline #${pipeline.id} for ${ref}. Status: ${pipeline.status}\nWeb URL: ${pipeline.web_url}`,
            },
          ],
        };
      }

      case "retry_pipeline": {
        const { project_id, pipeline_id } = RetryPipelineSchema.parse(params.arguments);
        const pipeline = await retryPipeline(project_id, pipeline_id);
        return {
          content: [
            {
              type: "text",
              text: `Retried pipeline #${pipeline.id}. Status: ${pipeline.status}\nWeb URL: ${pipeline.web_url}`,
            },
          ],
        };
      }

      case "cancel_pipeline": {
        const { project_id, pipeline_id } = CancelPipelineSchema.parse(params.arguments);
        const pipeline = await cancelPipeline(project_id, pipeline_id);
        return {
          content: [
            {
              type: "text",
              text: `Canceled pipeline #${pipeline.id}. Status: ${pipeline.status}\nWeb URL: ${pipeline.web_url}`,
            },
          ],
        };
      }

      case "play_pipeline_job": {
        const { project_id, job_id, job_variables_attributes } = PlayPipelineJobSchema.parse(
          params.arguments
        );
        const job = await playPipelineJob(project_id, job_id, job_variables_attributes);
        return {
          content: [
            {
              type: "text",
              text: `Ran job #${job.id} (${job.name}). Status: ${job.status}\nWeb URL: ${job.web_url}`,
            },
          ],
        };
      }

      case "retry_pipeline_job": {
        const { project_id, job_id } = RetryPipelineJobSchema.parse(params.arguments);
        const job = await retryPipelineJob(project_id, job_id);
        return {
          content: [
            {
              type: "text",
              text: `Retried job #${job.id} (${job.name}). Status: ${job.status}\nWeb URL: ${job.web_url}`,
            },
          ],
        };
      }

      case "cancel_pipeline_job": {
        const { project_id, job_id, force } = CancelPipelineJobSchema.parse(params.arguments);
        const job = await cancelPipelineJob(project_id, job_id, force);
        return {
          content: [
            {
              type: "text",
              text: `Canceled job #${job.id} (${job.name}). Status: ${job.status}\nWeb URL: ${job.web_url}`,
            },
          ],
        };
      }

      case "list_job_artifacts": {
        const { project_id, job_id, ...options } = ListJobArtifactsSchema.parse(
          params.arguments
        );
        const artifacts = await listJobArtifacts(project_id, job_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(artifacts, null, 2),
            },
          ],
        };
      }

      case "download_job_artifacts": {
        const { project_id, job_id, local_path } = DownloadJobArtifactsSchema.parse(
          params.arguments
        );
        const filePath = await downloadJobArtifacts(project_id, job_id, local_path);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({ success: true, file_path: filePath }, null, 2),
            },
          ],
        };
      }

      case "get_job_artifact_file": {
        const { project_id, job_id, artifact_path } = GetJobArtifactFileSchema.parse(
          params.arguments
        );
        const fileContent = await getJobArtifactFile(project_id, job_id, artifact_path);
        return {
          content: [
            {
              type: "text",
              text: fileContent,
            },
          ],
        };
      }

      case "list_merge_requests": {
        const { project_id, ...options } = ListMergeRequestsSchema.parse(params.arguments);

        // GitLab API treats _id and _username as mutually exclusive for these fields.
        // When both are provided, prefer _username and remove _id to avoid 400 errors.
        const cleanedOptions = { ...options } as Record<string, unknown>;
        if (cleanedOptions.author_id && cleanedOptions.author_username) {
          delete cleanedOptions.author_id;
        }
        if (cleanedOptions.assignee_id && cleanedOptions.assignee_username) {
          delete cleanedOptions.assignee_id;
        }
        if (cleanedOptions.reviewer_id && cleanedOptions.reviewer_username) {
          delete cleanedOptions.reviewer_id;
        }

        const mergeRequests = await listMergeRequests(project_id, cleanedOptions);
        return {
          content: [{ type: "text", text: JSON.stringify(mergeRequests, null, 2) }],
        };
      }

      case "list_milestones": {
        const { project_id, ...options } = ListProjectMilestonesSchema.parse(params.arguments);
        const milestones = await listProjectMilestones(project_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(milestones, null, 2),
            },
          ],
        };
      }

      case "get_milestone": {
        const { project_id, milestone_id } = GetProjectMilestoneSchema.parse(params.arguments);
        const milestone = await getProjectMilestone(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(milestone, null, 2),
            },
          ],
        };
      }

      case "create_milestone": {
        const { project_id, ...options } = CreateProjectMilestoneSchema.parse(params.arguments);
        const milestone = await createProjectMilestone(project_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(milestone, null, 2),
            },
          ],
        };
      }

      case "edit_milestone": {
        const { project_id, milestone_id, ...options } = EditProjectMilestoneSchema.parse(
          params.arguments
        );
        const milestone = await editProjectMilestone(project_id, milestone_id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(milestone, null, 2),
            },
          ],
        };
      }

      case "delete_milestone": {
        const { project_id, milestone_id } = DeleteProjectMilestoneSchema.parse(params.arguments);
        await deleteProjectMilestone(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  status: "success",
                  message: "Milestone deleted successfully",
                },
                null,
                2
              ),
            },
          ],
        };
      }

      case "get_milestone_issue": {
        const { project_id, milestone_id } = GetMilestoneIssuesSchema.parse(params.arguments);
        const issues = await getMilestoneIssues(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(issues, null, 2),
            },
          ],
        };
      }

      case "get_milestone_merge_requests": {
        const { project_id, milestone_id } = GetMilestoneMergeRequestsSchema.parse(
          params.arguments
        );
        const mergeRequests = await getMilestoneMergeRequests(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(mergeRequests, null, 2),
            },
          ],
        };
      }

      case "promote_milestone": {
        const { project_id, milestone_id } = PromoteProjectMilestoneSchema.parse(params.arguments);
        const milestone = await promoteProjectMilestone(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(milestone, null, 2),
            },
          ],
        };
      }

      case "get_milestone_burndown_events": {
        const { project_id, milestone_id } = GetMilestoneBurndownEventsSchema.parse(
          params.arguments
        );
        const events = await getMilestoneBurndownEvents(project_id, milestone_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(events, null, 2),
            },
          ],
        };
      }

      case "list_commits": {
        const args = ListCommitsSchema.parse(params.arguments);
        const commits = await listCommits(args.project_id, args);
        return {
          content: [{ type: "text", text: JSON.stringify(commits, null, 2) }],
        };
      }

      case "get_commit": {
        const args = GetCommitSchema.parse(params.arguments);
        const commit = await getCommit(args.project_id, args.sha, args.stats);
        return {
          content: [{ type: "text", text: JSON.stringify(commit, null, 2) }],
        };
      }

      case "get_commit_diff": {
        const args = GetCommitDiffSchema.parse(params.arguments);
        const diff = await getCommitDiff(args.project_id, args.sha, args.full_diff);
        return {
          content: [{ type: "text", text: JSON.stringify(diff, null, 2) }],
        };
      }

      case "list_group_iterations": {
        const args = ListGroupIterationsSchema.parse(params.arguments);
        const iterations = await listGroupIterations(args.group_id, args);
        return {
          content: [{ type: "text", text: JSON.stringify(iterations, null, 2) }],
        };
      }

      case "upload_markdown": {
        const args = MarkdownUploadSchema.parse(params.arguments);
        const upload = await markdownUpload(args.project_id, args.file_path);
        return {
          content: [{ type: "text", text: JSON.stringify(upload, null, 2) }],
        };
      }

      case "download_attachment": {
        const args = DownloadAttachmentSchema.parse(params.arguments);
        const result = await downloadAttachment(
          args.project_id,
          args.secret,
          args.filename,
          args.local_path
        );

        if (result.mimeType && !args.local_path) {
          // Return image inline as base64 so the AI can see it
          const base64 = result.buffer.toString("base64");
          return {
            content: [
              { type: "image", data: base64, mimeType: result.mimeType },
              {
                type: "text",
                text: JSON.stringify({ filename: result.filename, mimeType: result.mimeType }, null, 2),
              },
            ],
          };
        }

        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({ success: true, file_path: result.savedPath }, null, 2),
            },
          ],
        };
      }

      case "list_events": {
        const args = ListEventsSchema.parse(params.arguments);
        const events = await listEvents(args);
        return {
          content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
        };
      }

      case "get_project_events": {
        const args = GetProjectEventsSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const events = await getProjectEvents(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
        };
      }

      case "list_releases": {
        const args = ListReleasesSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const releases = await listReleases(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(releases, null, 2) }],
        };
      }

      case "get_release": {
        const args = GetReleaseSchema.parse(params.arguments);
        const release = await getRelease(
          args.project_id,
          args.tag_name,
          args.include_html_description
        );
        return {
          content: [{ type: "text", text: JSON.stringify(release, null, 2) }],
        };
      }

      case "create_release": {
        const args = CreateReleaseSchema.parse(params.arguments);
        const { project_id, ...options } = args;
        const release = await createRelease(project_id, options);
        return {
          content: [{ type: "text", text: JSON.stringify(release, null, 2) }],
        };
      }

      case "update_release": {
        const args = UpdateReleaseSchema.parse(params.arguments);
        const { project_id, tag_name, ...options } = args;
        const release = await updateRelease(project_id, tag_name, options);
        return {
          content: [{ type: "text", text: JSON.stringify(release, null, 2) }],
        };
      }

      case "delete_release": {
        const args = DeleteReleaseSchema.parse(params.arguments);
        const release = await deleteRelease(args.project_id, args.tag_name);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                { status: "success", message: "Release deleted successfully", release },
                null,
                2
              ),
            },
          ],
        };
      }

      case "create_release_evidence": {
        const args = CreateReleaseEvidenceSchema.parse(params.arguments);
        await createReleaseEvidence(args.project_id, args.tag_name);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                { status: "success", message: "Release evidence created successfully" },
                null,
                2
              ),
            },
          ],
        };
      }

      case "download_release_asset": {
        const args = DownloadReleaseAssetSchema.parse(params.arguments);
        const assetContent = await downloadReleaseAsset(
          args.project_id,
          args.tag_name,
          args.direct_asset_path
        );
        return {
          content: [{ type: "text", text: assetContent }],
        };
      }

      case "list_webhooks": {
        const args = ListWebhooksSchema.parse(params.arguments);
        const webhooks = await listWebhooks(args);
        return {
          content: [{ type: "text", text: JSON.stringify(webhooks, null, 2) }],
        };
      }

      case "list_webhook_events": {
        const args = ListWebhookEventsSchema.parse(params.arguments);
        const events = await listWebhookEvents(args);
        return {
          content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
        };
      }

      case "get_webhook_event": {
        const args = GetWebhookEventSchema.parse(params.arguments);
        const event = await getWebhookEvent(args);
        if (!event) {
          const searchScope = args.page
            ? `on page ${args.page}`
            : "in the 500 most recent events";
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(
                  { error: `Webhook event ${args.event_id} not found ${searchScope}` },
                  null,
                  2
                ),
              },
            ],
          };
        }
        return {
          content: [{ type: "text", text: JSON.stringify(event, null, 2) }],
        };
      }

      default:
        throw new Error(`Unknown tool: ${params.name}`);
    }
  } catch (error) {
    logger.debug(params);
    if (error instanceof z.ZodError) {
      throw new Error(
        `Invalid arguments: ${error.errors
          .map(e => `${e.path.join(".")}: ${e.message}`)
          .join(", ")}`
      );
    }
    throw error;
  }
}

/**
 *  Color constants for terminal output
 */
const colorGreen = "\x1b[32m";
const colorReset = "\x1b[0m";

/**
 * Determine the transport mode based on environment variables and availability
 *
 * Transport mode priority (highest to lowest):
 * 1. STREAMABLE_HTTP
 * 2. SSE
 * 3. STDIO
 */
function determineTransportMode(): TransportMode {
  // Check for streamable-http support (highest priority)
  if (STREAMABLE_HTTP) {
    return TransportMode.STREAMABLE_HTTP;
  }

  // Check for SSE support (medium priority)
  if (SSE) {
    return TransportMode.SSE;
  }

  // Default to stdio (lowest priority)
  return TransportMode.STDIO;
}

/**
 * Start server with stdio transport
 */
async function startStdioServer(): Promise<void> {
  const serverInstance = createServer();
  const transport = new StdioServerTransport();
  transport.onclose = () => {
    logger.info("Stdio transport closed, releasing client pool");
    clientPool.closeAll();
  };
  await serverInstance.connect(transport);
}

/**
 * Start server with traditional SSE transport
 */
async function startSSEServer(): Promise<void> {
  const app = express();
  const transports: { [sessionId: string]: SSEServerTransport } = {};
  let shuttingDown = false;

  app.get("/sse", async (_: Request, res: Response) => {
    const serverInstance = createServer();
    const transport = new SSEServerTransport("/messages", res);
    transports[transport.sessionId] = transport;
    res.on("close", () => {
      delete transports[transport.sessionId];
    });
    await serverInstance.connect(transport);
  });

  app.post("/messages", async (req: Request, res: Response) => {
    const sessionId = req.query.sessionId as string;
    const transport = transports[sessionId];
    if (transport) {
      await transport.handlePostMessage(req, res);
    } else {
      res.status(400).send("No transport found for sessionId");
    }
  });

  app.get("/health", (_: Request, res: Response) => {
    res.status(200).json({
      status: "healthy",
      version: SERVER_VERSION,
      transport: TransportMode.SSE,
    });
  });

  const httpServer = app.listen(Number(PORT), HOST, () => {
    logger.info("GitLab MCP Server running with SSE transport");
    logger.info(`${colorGreen}Endpoint: http://${HOST}:${PORT}/sse${colorReset}`);
  });

  const shutdown = async (signal: string) => {
    if (shuttingDown) return;
    shuttingDown = true;
    logger.info(`${signal} received, shutting down SSE server...`);
    httpServer.close(() => logger.info("SSE HTTP server closed"));
    await Promise.allSettled(
      Object.values(transports).map(async transport => {
        try {
          await transport.close();
        } catch (error) {
          logger.error("Error closing SSE transport:", error);
        }
      })
    );
    clientPool.closeAll();
    process.exit(0);
  };

  process.on("SIGTERM", () => {
    void shutdown("SIGTERM");
  });
  process.on("SIGINT", () => {
    void shutdown("SIGINT");
  });
}

/**
 * Start server with Streamable HTTP transport
 */
async function startStreamableHTTPServer(): Promise<void> {
  const app = express();
  const streamableTransports: {
    [sessionId: string]: StreamableHTTPServerTransport;
  } = {};

  const authTimeouts: Record<string, NodeJS.Timeout> = {};

  // Configuration and limits
  const MAX_SESSIONS = Number.parseInt(process.env.MAX_SESSIONS || "1000", 10);
  const MAX_REQUESTS_PER_MINUTE = Number.parseInt(process.env.MAX_REQUESTS_PER_MINUTE || "60", 10);

  // Metrics tracking
  const metrics = {
    activeSessions: 0,
    totalSessions: 0,
    expiredSessions: 0,
    authFailures: 0,
    requestsProcessed: 0,
    rejectedByRateLimit: 0,
    rejectedByCapacity: 0,
  };

  // Rate limiting per session
  const sessionRequestCounts: Record<string, { count: number; resetAt: number }> = {};

  /**
   * Validate token format and length
   */
  const validateToken = (token: string): boolean => {
    // GitLab PAT format: glpat-xxxxx (min 20 chars)
    if (token.length < 20) return false;
    if (!/^[-a-zA-Z0-9_.]+$/.test(token)) return false;
    return true;
  };

  /**
   * Check rate limit for session
   */
  const checkRateLimit = (sessionId: string): boolean => {
    const now = Date.now();
    const session = sessionRequestCounts[sessionId];

    if (!session || now > session.resetAt) {
      sessionRequestCounts[sessionId] = { count: 1, resetAt: now + 60000 };
      return true;
    }

    if (session.count >= MAX_REQUESTS_PER_MINUTE) {
      return false;
    }

    session.count++;
    return true;
  };

  /**
   * Check whether the request carries a raw header auth token (Private-Token or JOB-TOKEN).
   * Used to decide whether to bypass OAuth validation.
   */
  const hasHeaderAuth = (req: Request): boolean => {
    return !!(
      (req.headers["private-token"] as string | undefined) ||
      (req.headers["job-token"] as string | undefined)
    );
  };

  /**
   * Parse authentication from request headers
   * Returns null if no auth found or invalid format
   * Supports: Private-Token header, JOB-TOKEN header, Authorization Bearer header
   * Priority: Private-Token > JOB-TOKEN > Authorization Bearer
   */
  const parseAuthHeaders = (req: Request): AuthData | null => {
    const authHeader = (req.headers["authorization"] as string | undefined) || "";
    const privateToken = (req.headers["private-token"] as string | undefined) || "";
    const jobToken = (req.headers["job-token"] as string | undefined) || "";
    const dynamicApiUrl = (req.headers["x-gitlab-api-url"] as string | undefined)?.trim();

    let apiUrl = GITLAB_API_URL; // Default API URL

    // Only process dynamic URL if the feature is enabled
    if (ENABLE_DYNAMIC_API_URL && dynamicApiUrl) {
      try {
        new URL(dynamicApiUrl); // Ensure it's a valid URL format
        apiUrl = normalizeGitLabApiUrl(dynamicApiUrl);
      } catch {
        logger.warn(`Invalid X-GitLab-API-URL provided: ${dynamicApiUrl}. Auth will fail.`);
        return null; // Reject if URL is malformed
      }
    }

    // Extract token — priority: Private-Token > JOB-TOKEN > Authorization Bearer
    // PATs are preferred over job tokens because they carry broader permissions.
    let token: string | null = null;
    let header: "Authorization" | "Private-Token" | "JOB-TOKEN" | null = null;

    if (privateToken) {
      token = privateToken.trim();
      header = "Private-Token";
    } else if (jobToken) {
      token = jobToken.trim();
      header = "JOB-TOKEN";
    } else if (authHeader) {
      // Use \S+ instead of .+ to prevent ReDoS attacks
      // \S+ only matches non-whitespace, so trim() is technically unnecessary,
      // but we keep it for defensive coding and backward compatibility
      const match = /^Bearer\s+(\S+)$/i.exec(authHeader);
      if (match) {
        token = match[1].trim();
        header = "Authorization";
      }
    }

    // Validate token and return AuthData object
    if (token && header && validateToken(token)) {
      return { header, token, lastUsed: Date.now(), apiUrl };
    }

    return null;
  };

  /**
   * Set or reset timeout for session auth
   * After SESSION_TIMEOUT_SECONDS of inactivity, the auth token is removed
   * but the transport session remains active
   */
  const setAuthTimeout = (sessionId: string) => {
    // Clear existing timeout if any
    clearAuthTimeout(sessionId);

    // Set new timeout
    authTimeouts[sessionId] = setTimeout(() => {
      if (authBySession[sessionId]) {
        logger.info(
          `Session ${sessionId}: auth token expired after ${SESSION_TIMEOUT_SECONDS}s of inactivity`
        );
        delete authBySession[sessionId];
        delete authTimeouts[sessionId];
        metrics.expiredSessions++;
      }
    }, SESSION_TIMEOUT_SECONDS * 1000);
  };

  /**
   * Clear timeout for session auth
   */
  const clearAuthTimeout = (sessionId: string) => {
    const timeout = authTimeouts[sessionId];
    if (timeout) {
      clearTimeout(timeout);
      delete authTimeouts[sessionId];
    }
  };

  /**
   * Clean up session auth data
   */
  const cleanupSessionAuth = (sessionId: string) => {
    delete authBySession[sessionId];
    clearAuthTimeout(sessionId);
  };

  // Configure Express middleware
  app.use(express.json());

  // MCP OAuth — mount auth router and prepare bearer-auth middleware
  if (GITLAB_MCP_OAUTH) {
    // Trust first proxy so express-rate-limit uses X-Forwarded-For for real client IP.
    // Only enabled in OAuth mode where the server is typically behind a reverse proxy.
    app.set("trust proxy", 1);
    const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4\/?$/, "").replace(/\/$/, "");
    const issuerUrl = new URL(MCP_SERVER_URL!);
    const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID!, "GitLab MCP Server", GITLAB_READ_ONLY_MODE, GITLAB_OAUTH_SCOPES);

    // Mounts /.well-known/oauth-authorization-server,
    //        /.well-known/oauth-protected-resource,
    //        /authorize, /token, /register, /revoke
    app.use(
      mcpAuthRouter({
        provider: oauthProvider,
        issuerUrl,
        baseUrl: issuerUrl,
        scopesSupported: GITLAB_OAUTH_SCOPES ?? ["api", "read_api", "read_user"],
        resourceName: "GitLab MCP Server",
      })
    );

    // Expose provider so the /mcp route middleware can reference it
    (app as any)._mcpOAuthProvider = oauthProvider;
  }

  // Build bearer-auth middleware — no-op unless GITLAB_MCP_OAUTH is enabled.
  // Unauthenticated requests receive 401 + WWW-Authenticate header, which is
  // exactly what Claude.ai needs to trigger the OAuth browser flow.
  //
  // Header auth fallback: if Private-Token or JOB-TOKEN headers are present,
  // OAuth validation is skipped and the raw token is used directly per-session.
  // Note: Authorization: Bearer is always treated as an OAuth token and goes
  // through OAuth validation — use Private-Token for PAT-based header auth.
  const oauthBearerAuth = GITLAB_MCP_OAUTH
    ? requireBearerAuth({
        verifier: (app as any)._mcpOAuthProvider,
        requiredScopes: [],
      })
    : undefined;
  const mcpBearerAuth = GITLAB_MCP_OAUTH
    ? (req: Request, res: Response, next: NextFunction) => {
        const privateToken = (req.headers["private-token"] as string | undefined) || "";
        const jobToken = (req.headers["job-token"] as string | undefined) || "";
        if (privateToken || jobToken) {
          // Validate the raw token before bypassing OAuth
          const authData = parseAuthHeaders(req);
          if (authData) {
            next();
            return;
          }
          res.status(401).json({
            error: "Invalid Private-Token or JOB-TOKEN header",
            message: "The provided token failed validation. Check the token value and format.",
          });
          return;
        }
        oauthBearerAuth!(req, res, next);
      }
    : (_req: Request, _res: Response, next: NextFunction) => next();

  // Streamable HTTP endpoint - handles both session creation and message handling
  app.post("/mcp", mcpBearerAuth, async (req: Request, res: Response) => {
    const sessionId = req.headers["mcp-session-id"] as string;

    // Track request
    metrics.requestsProcessed++;

    // Rate limiting check for existing sessions
    if ((REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId && !checkRateLimit(sessionId)) {
      metrics.rejectedByRateLimit++;
      res.status(429).json({
        error: "Rate limit exceeded",
        message: `Maximum ${MAX_REQUESTS_PER_MINUTE} requests per minute allowed`,
      });
      return;
    }

    // Capacity check for new sessions
    if (!sessionId && Object.keys(streamableTransports).length >= MAX_SESSIONS) {
      metrics.rejectedByCapacity++;
      res.status(503).json({
        error: "Server capacity reached",
        message: `Maximum ${MAX_SESSIONS} concurrent sessions allowed. Please try again later.`,
      });
      return;
    }

    // Handle remote authorization: extract and store auth headers per session
    if (REMOTE_AUTHORIZATION) {
      const authData = parseAuthHeaders(req);

      if (sessionId && !authBySession[sessionId]) {
        // New session: require auth headers
        if (!authData) {
          metrics.authFailures++;
          res.status(401).json({
            error: "Missing Private-Token, JOB-TOKEN, or Authorization header",
            message:
              "Remote authorization is enabled. Please provide Private-Token, JOB-TOKEN, or Authorization header.",
          });
          return;
        }
        // Store auth for this session
        authBySession[sessionId] = authData;
        logger.info(`Session ${sessionId}: stored ${authData.header} header`);
        setAuthTimeout(sessionId);
      } else if (sessionId && authData) {
        // Existing session: allow auth rotation/update
        authBySession[sessionId] = authData;
        logger.debug(`Session ${sessionId}: updated ${authData.header} header`);
        setAuthTimeout(sessionId);
      } else if (sessionId && authBySession[sessionId]) {
        // Existing session with stored auth: update last used time and reset timeout
        authBySession[sessionId].lastUsed = Date.now();
        setAuthTimeout(sessionId);
      } else if (!sessionId && !authData) {
        // First request without session - will fail in initialization
      }
    }

    // MCP OAuth mode — either header auth (PAT/job token) or OAuth Bearer token.
    // Header auth takes precedence: if Private-Token or JOB-TOKEN is present the
    // OAuth middleware was bypassed and we store the raw token per-session.
    // Otherwise req.auth is populated by requireBearerAuth; store the OAuth token.
    if (GITLAB_MCP_OAUTH) {
      const headerAuthData = hasHeaderAuth(req) ? parseAuthHeaders(req) : null;

      if (headerAuthData) {
        if (headerAuthData && sessionId) {
          if (!authBySession[sessionId]) {
            authBySession[sessionId] = headerAuthData;
            logger.info(
              `Session ${sessionId}: stored ${headerAuthData.header} header (header auth)`
            );
            setAuthTimeout(sessionId);
          } else {
            authBySession[sessionId] = {
              ...authBySession[sessionId],
              header: headerAuthData.header,
              token: headerAuthData.token,
              lastUsed: Date.now(),
            };
            setAuthTimeout(sessionId);
          }
        }
      } else {
        const authInfo = req.auth;
        if (authInfo?.token && sessionId) {
          if (!authBySession[sessionId]) {
            authBySession[sessionId] = {
              header: "Authorization",
              token: authInfo.token,
              lastUsed: Date.now(),
              apiUrl: GITLAB_API_URL,
            };
            logger.info(
              `Session ${sessionId}: stored OAuth token (client: ${authInfo.clientId})`
            );
            setAuthTimeout(sessionId);
          } else {
            // Update token on every request — the client may have refreshed it
            authBySession[sessionId].token = authInfo.token;
            authBySession[sessionId].lastUsed = Date.now();
            setAuthTimeout(sessionId);
          }
        }
      }
    }

    // Handle request with proper AsyncLocalStorage context
    const handleRequest = async () => {
      try {
        let transport: StreamableHTTPServerTransport;

        if (sessionId && streamableTransports[sessionId]) {
          // Reuse existing transport for ongoing session
          transport = streamableTransports[sessionId];

          await transport.handleRequest(req, res, req.body);
        } else {
          // Create new transport for new session
          transport = new StreamableHTTPServerTransport({
            sessionIdGenerator: () => randomUUID(),
            onsessioninitialized: (newSessionId: string) => {
              streamableTransports[newSessionId] = transport;
              metrics.totalSessions++;
              metrics.activeSessions++;
              logger.warn(`Streamable HTTP session initialized: ${newSessionId}`);

              // Store auth for newly created session in remote mode
              if (REMOTE_AUTHORIZATION && !authBySession[newSessionId]) {
                const authData = parseAuthHeaders(req);
                if (authData) {
                  authBySession[newSessionId] = authData;
                  logger.info(`Session ${newSessionId}: stored ${authData.header} header`);
                  setAuthTimeout(newSessionId);
                }
              }

              // Store OAuth token for newly created session in MCP OAuth mode.
              // If Private-Token or JOB-TOKEN headers are present, prefer them.
              if (GITLAB_MCP_OAUTH && !authBySession[newSessionId]) {
                if (hasHeaderAuth(req)) {
                  const authData = parseAuthHeaders(req);
                  if (authData) {
                    authBySession[newSessionId] = authData;
                    logger.info(
                      `Session ${newSessionId}: stored ${authData.header} header (header auth)`
                    );
                    setAuthTimeout(newSessionId);
                  }
                } else {
                  const authInfo = req.auth;
                  if (authInfo?.token) {
                    authBySession[newSessionId] = {
                      header: "Authorization",
                      token: authInfo.token,
                      lastUsed: Date.now(),
                      apiUrl: GITLAB_API_URL,
                    };
                    logger.info(
                      `Session ${newSessionId}: stored OAuth token (client: ${authInfo.clientId})`
                    );
                    setAuthTimeout(newSessionId);
                  }
                }
              }
            },
          });

          // Set up cleanup handler when transport closes
          transport.onclose = () => {
            const sid = transport.sessionId;
            if (sid && streamableTransports[sid]) {
              logger.warn(`Streamable HTTP transport closed for session ${sid}, cleaning up`);
              delete streamableTransports[sid];
              metrics.activeSessions--;
              if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
                cleanupSessionAuth(sid);
                delete sessionRequestCounts[sid];
                logger.info(`Session ${sid}: cleaned up auth mapping`);
              }
            }
          };

          // Create a new Server instance per session to prevent
          // cross-client data leakage (GHSA-345p-7cg4-v4c7)
          const serverInstance = createServer();
          await serverInstance.connect(transport);

          // Handle the request - context is already set up in the outer handleRequest wrapper
          await transport.handleRequest(req, res, req.body);
        }
      } catch (error) {
        logger.error("Streamable HTTP error:", error);
        res.status(500).json({
          error: "Internal server error",
          message: error instanceof Error ? error.message : "Unknown error",
        });
      }
    };

    // Execute with auth context in remote mode (REMOTE_AUTHORIZATION or GITLAB_MCP_OAUTH)
    if ((REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId && authBySession[sessionId]) {
      const authData = authBySession[sessionId];
      const ctx: SessionAuth = {
        sessionId,
        header: authData.header,
        token: authData.token,
        lastUsed: authData.lastUsed,
        apiUrl: authData.apiUrl,
      };

      // Run the entire request handling within AsyncLocalStorage context
      await sessionAuthStore.run(ctx, handleRequest);
    } else {
      // Standard execution (no per-session auth or no session yet)
      await handleRequest();
    }
  });

  // Reject unsupported methods on /mcp
  app.get("/mcp", (_req: Request, res: Response) => {
    res.setHeader("Allow", "POST, DELETE");
    res.status(405).json({
      error: "Method Not Allowed",
      message:
        "GET /mcp is not supported when STREAMABLE_HTTP is enabled. Use POST to communicate with the MCP server.",
    });
  });

  // Metrics endpoint
  app.get("/metrics", (_req: Request, res: Response) => {
    res.json({
      ...metrics,
      activeSessions: Object.keys(streamableTransports).length,
      authenticatedSessions: Object.keys(authBySession).length,
      gitlabClientPool: clientPool.getStats(),
      uptime: process.uptime(),
      memoryUsage: process.memoryUsage(),
      config: {
        maxSessions: MAX_SESSIONS,
        maxRequestsPerMinute: MAX_REQUESTS_PER_MINUTE,
        sessionTimeoutSeconds: SESSION_TIMEOUT_SECONDS,
        remoteAuthEnabled: REMOTE_AUTHORIZATION,
        mcpOAuthEnabled: GITLAB_MCP_OAUTH,
      },
    });
  });

  // Health check endpoint
  app.get("/health", (_req: Request, res: Response) => {
    const isHealthy = Object.keys(streamableTransports).length < MAX_SESSIONS;
    res.status(isHealthy ? 200 : 503).json({
      status: isHealthy ? "healthy" : "degraded",
      activeSessions: Object.keys(streamableTransports).length,
      maxSessions: MAX_SESSIONS,
      uptime: process.uptime(),
    });
  });

  // to delete a mcp server session explicitly
  app.delete("/mcp", async (req: Request, res: Response) => {
    const sessionId = req.headers["mcp-session-id"] as string;

    if (!sessionId) {
      res.status(400).json({ error: "mcp-session-id header is required" });
      return;
    }

    const transport = streamableTransports[sessionId];

    if (transport) {
      try {
        await transport.close();
        logger.info(`Explicitly closed session via DELETE request: ${sessionId}`);
        if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
          cleanupSessionAuth(sessionId);
          delete sessionRequestCounts[sessionId];
          logger.info(`Session ${sessionId}: cleaned up auth mapping on DELETE`);
        }
        res.status(204).send();
      } catch (error) {
        logger.error(`Error closing session ${sessionId}:`, error);
        res.status(500).json({ error: "Failed to close session" });
      }
    } else {
      res.status(404).json({ error: "Session not found" });
    }
  });

  // Start server
  const httpServer = app.listen(Number(PORT), HOST, () => {
    logger.info(`GitLab MCP Server running with Streamable HTTP transport`);
    logger.info(`${colorGreen}Endpoint: http://${HOST}:${PORT}/mcp${colorReset}`);
  });

  // Graceful shutdown handler
  const gracefulShutdown = async (signal: string) => {
    logger.info(`${signal} received, starting graceful shutdown...`);

    // Stop accepting new connections
    httpServer.close(() => {
      logger.info("HTTP server closed");
    });

    // Close all active sessions
    const sessionIds = Object.keys(streamableTransports);
    logger.info(`Closing ${sessionIds.length} active sessions...`);

    const closePromises = sessionIds.map(async sessionId => {
      try {
        const transport = streamableTransports[sessionId];
        if (transport) {
          await transport.close();
          if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
            cleanupSessionAuth(sessionId);
            delete sessionRequestCounts[sessionId];
          }
        }
      } catch (error) {
        logger.error(`Error closing session ${sessionId}:`, error);
      }
    });

    await Promise.allSettled(closePromises);

    // Clear all timeouts
    Object.keys(authTimeouts).forEach(sessionId => {
      clearAuthTimeout(sessionId);
    });

    clientPool.closeAll();
    logger.info("Graceful shutdown complete");
    process.exit(0);
  };

  // Register signal handlers
  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
  process.on("SIGINT", () => gracefulShutdown("SIGINT"));
}

/**
 * Initialize server with specific transport mode
 * Handle transport-specific initialization logic
 */
async function initializeServerByTransportMode(mode: TransportMode): Promise<void> {
  logger.info("Initializing server with transport mode:", mode);
  switch (mode) {
    case TransportMode.STDIO:
      logger.warn("Starting GitLab MCP Server with stdio transport");
      await startStdioServer();
      break;

    case TransportMode.SSE:
      logger.warn("Starting GitLab MCP Server with SSE transport");
      await startSSEServer();
      break;

    case TransportMode.STREAMABLE_HTTP:
      logger.warn("Starting GitLab MCP Server with Streamable HTTP transport");
      await startStreamableHTTPServer();
      break;

    default: {
      // This should never happen with proper enum usage, but TypeScript requires it
      const exhaustiveCheck: never = mode;
      throw new Error(`Unknown transport mode: ${exhaustiveCheck}`);
    }
  }
}

/**
 * Initialize and run the server
 * Main entry point for server startup
 */
async function runServer() {
  try {
    // Validate configuration before starting server
    validateConfiguration();

    // Initialize OAuth token if OAuth is enabled
    if (USE_OAUTH) {
      logger.info("Using OAuth authentication...");
      try {
        const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4$/, "");
        const oauthResult = await initializeOAuthClient(gitlabBaseUrl);
        oauthClient = oauthResult.client;
        OAUTH_ACCESS_TOKEN = oauthResult.accessToken;
        logger.info("OAuth authentication successful");
      } catch (error) {
        logger.error("OAuth authentication failed:", error);
        process.exit(1);
      }
    }

    const transportMode = determineTransportMode();
    await initializeServerByTransportMode(transportMode);

    logger.info(`Configured GitLab API URLs: ${GITLAB_API_URLS.join(", ")}`);
    logger.info(`Default GitLab API URL: ${GITLAB_API_URL}`);
  } catch (error) {
    logger.error("Error initializing server:", error);
    process.exit(1);
  }
}

// 下記の２行を追記
runServer().catch(error => {
  logger.error("Fatal error in main():", error);
  process.exit(1);
});