@structured-world/gitlab-mcp 6.62.1 → 7.0.1

package/dist/src/utils/error-handler.js

@@ -12,228 +12,230 @@ exports.createVersionRestrictedError = createVersionRestrictedError;
 exports.parseGitLabApiError = parseGitLabApiError;
 exports.parseTimeoutError = parseTimeoutError;
 exports.isStructuredToolError = isStructuredToolError;
+exports.classifyError = classifyError;
+exports.createConnectionFailedError = createConnectionFailedError;
 const ConnectionManager_js_1 = require("../services/ConnectionManager.js");
 const version_js_1 = require("./version.js");
 const FEATURE_METADATA = {
     workItems: {
-        name: "Work Items",
-        requiredTier: "Free",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/work_items/",
+        name: 'Work Items',
+        requiredTier: 'Free',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/work_items/',
         alternatives: [],
     },
     epics: {
-        name: "Epics",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/epics/",
+        name: 'Epics',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/epics/',
         alternatives: [
             {
-                action: "Use issues for tracking",
-                description: "Create issues with labels to organize work instead of epics",
-                available_on: "Free",
+                action: 'Use issues for tracking',
+                description: 'Create issues with labels to organize work instead of epics',
+                available_on: 'Free',
             },
             {
-                action: "Use milestones",
-                description: "Group related issues under milestones for release planning",
-                available_on: "Free",
+                action: 'Use milestones',
+                description: 'Group related issues under milestones for release planning',
+                available_on: 'Free',
             },
         ],
     },
     iterations: {
-        name: "Iterations",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/iterations/",
+        name: 'Iterations',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/iterations/',
         alternatives: [
             {
-                action: "Use milestones",
-                description: "Use milestones to track time-boxed work periods",
-                available_on: "Free",
+                action: 'Use milestones',
+                description: 'Use milestones to track time-boxed work periods',
+                available_on: 'Free',
             },
         ],
     },
     roadmaps: {
-        name: "Roadmaps",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/roadmap/",
+        name: 'Roadmaps',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/roadmap/',
         alternatives: [
             {
-                action: "Use milestone views",
-                description: "View milestones timeline for basic roadmap functionality",
-                available_on: "Free",
+                action: 'Use milestone views',
+                description: 'View milestones timeline for basic roadmap functionality',
+                available_on: 'Free',
             },
         ],
     },
     portfolioManagement: {
-        name: "Portfolio Management",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/planning_hierarchy/",
+        name: 'Portfolio Management',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/planning_hierarchy/',
         alternatives: [
             {
-                action: "Use group-level milestones",
-                description: "Track progress across projects using group milestones",
-                available_on: "Free",
+                action: 'Use group-level milestones',
+                description: 'Track progress across projects using group milestones',
+                available_on: 'Free',
             },
         ],
     },
     advancedSearch: {
-        name: "Advanced Search",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/search/advanced_search.html",
+        name: 'Advanced Search',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/search/advanced_search.html',
         alternatives: [
             {
-                action: "Use basic search",
-                description: "Use standard GitLab search functionality",
-                available_on: "Free",
+                action: 'Use basic search',
+                description: 'Use standard GitLab search functionality',
+                available_on: 'Free',
             },
         ],
     },
     codeReview: {
-        name: "Code Review Analytics",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/analytics/code_review_analytics.html",
+        name: 'Code Review Analytics',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/analytics/code_review_analytics.html',
         alternatives: [],
     },
     securityDashboard: {
-        name: "Security Dashboard",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/application_security/security_dashboard/",
+        name: 'Security Dashboard',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/',
         alternatives: [],
     },
     complianceFramework: {
-        name: "Compliance Framework",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/settings/compliance_frameworks.html",
+        name: 'Compliance Framework',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/settings/compliance_frameworks.html',
         alternatives: [],
     },
     valueStreamAnalytics: {
-        name: "Value Stream Analytics",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/value_stream_analytics/",
+        name: 'Value Stream Analytics',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/value_stream_analytics/',
         alternatives: [],
     },
     customFields: {
-        name: "Custom Fields",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/working_with_projects.html",
+        name: 'Custom Fields',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/working_with_projects.html',
         alternatives: [
             {
-                action: "Use labels",
-                description: "Use labels to categorize and tag work items",
-                available_on: "Free",
+                action: 'Use labels',
+                description: 'Use labels to categorize and tag work items',
+                available_on: 'Free',
             },
         ],
     },
     okrs: {
-        name: "OKRs (Objectives and Key Results)",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/okrs/",
+        name: 'OKRs (Objectives and Key Results)',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/okrs/',
         alternatives: [
             {
-                action: "Use issues with labels",
-                description: "Track objectives as issues with specific labels",
-                available_on: "Free",
+                action: 'Use issues with labels',
+                description: 'Track objectives as issues with specific labels',
+                available_on: 'Free',
             },
         ],
     },
     healthStatus: {
-        name: "Health Status",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#health-status",
+        name: 'Health Status',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#health-status',
         alternatives: [
             {
-                action: "Use labels for status",
+                action: 'Use labels for status',
                 description: "Create labels like 'on-track', 'at-risk', 'needs-attention'",
-                available_on: "Free",
+                available_on: 'Free',
             },
         ],
     },
     weight: {
-        name: "Issue Weight",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/issues/issue_weight.html",
+        name: 'Issue Weight',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/issues/issue_weight.html',
         alternatives: [
             {
-                action: "Use labels for estimation",
+                action: 'Use labels for estimation',
                 description: "Create labels like 'size::S', 'size::M', 'size::L' for estimation",
-                available_on: "Free",
+                available_on: 'Free',
             },
         ],
     },
     multiLevelEpics: {
-        name: "Multi-level Epics",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/group/epics/manage_epics.html#multi-level-child-epics",
+        name: 'Multi-level Epics',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/group/epics/manage_epics.html#multi-level-child-epics',
         alternatives: [
             {
-                action: "Use flat epics",
-                description: "Organize work with single-level epics (Premium)",
-                available_on: "Premium",
+                action: 'Use flat epics',
+                description: 'Organize work with single-level epics (Premium)',
+                available_on: 'Premium',
             },
         ],
     },
     serviceDesk: {
-        name: "Service Desk",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/service_desk/",
+        name: 'Service Desk',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/service_desk/',
         alternatives: [],
     },
     requirements: {
-        name: "Requirements Management",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/requirements/",
+        name: 'Requirements Management',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/requirements/',
         alternatives: [
             {
-                action: "Use issues",
-                description: "Track requirements as issues with a dedicated label",
-                available_on: "Free",
+                action: 'Use issues',
+                description: 'Track requirements as issues with a dedicated label',
+                available_on: 'Free',
             },
         ],
     },
     qualityManagement: {
-        name: "Quality Management",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/ci/testing/",
+        name: 'Quality Management',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/ci/testing/',
         alternatives: [],
     },
     timeTracking: {
-        name: "Time Tracking",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/time_tracking.html",
+        name: 'Time Tracking',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/time_tracking.html',
         alternatives: [],
     },
     crmContacts: {
-        name: "CRM Contacts",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/crm/",
+        name: 'CRM Contacts',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/crm/',
         alternatives: [],
     },
     vulnerabilities: {
-        name: "Vulnerability Management",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/user/application_security/vulnerabilities/",
+        name: 'Vulnerability Management',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/user/application_security/vulnerabilities/',
         alternatives: [],
     },
     errorTracking: {
-        name: "Error Tracking",
-        requiredTier: "Ultimate",
-        docsUrl: "https://docs.gitlab.com/ee/operations/error_tracking.html",
+        name: 'Error Tracking',
+        requiredTier: 'Ultimate',
+        docsUrl: 'https://docs.gitlab.com/ee/operations/error_tracking.html',
         alternatives: [],
     },
     designManagement: {
-        name: "Design Management",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/issues/design_management.html",
+        name: 'Design Management',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/issues/design_management.html',
         alternatives: [],
     },
     linkedResources: {
-        name: "Linked Resources",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/issues/related_issues.html",
+        name: 'Linked Resources',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/issues/related_issues.html',
         alternatives: [],
     },
     emailParticipants: {
-        name: "Email Participants",
-        requiredTier: "Premium",
-        docsUrl: "https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#add-an-email-participant",
+        name: 'Email Participants',
+        requiredTier: 'Premium',
+        docsUrl: 'https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#add-an-email-participant',
         alternatives: [],
     },
 };
@@ -247,31 +249,31 @@ function detectTierRestriction(tool, action, toolArgs) {
     }
     const currentTierRaw = connectionManager.getTier();
     const currentTier = normalizeTier(currentTierRaw);
-    if (tool === "browse_work_items" || tool === "manage_work_item") {
+    if (tool === 'browse_work_items' || tool === 'manage_work_item') {
         const restriction = checkWorkItemTypeRestriction(connectionManager, toolArgs, currentTier);
         if (restriction)
             return restriction;
     }
-    if (tool === "browse_iterations") {
-        if (!connectionManager.isFeatureAvailable("iterations")) {
-            return createRestrictionInfo("iterations", currentTier);
+    if (tool === 'browse_iterations') {
+        if (!connectionManager.isFeatureAvailable('iterations')) {
+            return createRestrictionInfo('iterations', currentTier);
         }
     }
-    if ((tool === "browse_webhooks" || tool === "manage_webhook") && toolArgs?.scope === "group") {
-        if (!connectionManager.isFeatureAvailable("serviceDesk")) {
+    if ((tool === 'browse_webhooks' || tool === 'manage_webhook') && toolArgs?.scope === 'group') {
+        if (!connectionManager.isFeatureAvailable('serviceDesk')) {
             return {
-                feature: "serviceDesk",
-                name: "Group Webhooks",
-                requiredTier: "Premium",
+                feature: 'serviceDesk',
+                name: 'Group Webhooks',
+                requiredTier: 'Premium',
                 currentTier,
                 alternatives: [
                     {
-                        action: "Use project-level webhooks",
-                        description: "Configure webhooks on individual projects instead",
-                        available_on: "Free",
+                        action: 'Use project-level webhooks',
+                        description: 'Configure webhooks on individual projects instead',
+                        available_on: 'Free',
                     },
                 ],
-                docsUrl: "https://docs.gitlab.com/ee/user/project/integrations/webhooks.html",
+                docsUrl: 'https://docs.gitlab.com/ee/user/project/integrations/webhooks.html',
             };
         }
     }
@@ -281,19 +283,19 @@ function checkWorkItemTypeRestriction(connectionManager, toolArgs, currentTier)
     if (!toolArgs)
         return null;
     const types = extractWorkItemTypes(toolArgs);
-    if (types.includes("EPIC")) {
-        if (!connectionManager.isFeatureAvailable("epics")) {
-            return createRestrictionInfo("epics", currentTier);
+    if (types.includes('EPIC')) {
+        if (!connectionManager.isFeatureAvailable('epics')) {
+            return createRestrictionInfo('epics', currentTier);
         }
     }
-    if (types.includes("OBJECTIVE") || types.includes("KEY_RESULT")) {
-        if (!connectionManager.isFeatureAvailable("okrs")) {
-            return createRestrictionInfo("okrs", currentTier);
+    if (types.includes('OBJECTIVE') || types.includes('KEY_RESULT')) {
+        if (!connectionManager.isFeatureAvailable('okrs')) {
+            return createRestrictionInfo('okrs', currentTier);
         }
     }
-    if (types.includes("REQUIREMENT")) {
-        if (!connectionManager.isFeatureAvailable("requirements")) {
-            return createRestrictionInfo("requirements", currentTier);
+    if (types.includes('REQUIREMENT')) {
+        if (!connectionManager.isFeatureAvailable('requirements')) {
+            return createRestrictionInfo('requirements', currentTier);
         }
     }
     return null;
@@ -301,12 +303,12 @@ function checkWorkItemTypeRestriction(connectionManager, toolArgs, currentTier)
 function extractWorkItemTypes(toolArgs) {
     const types = [];
     if (Array.isArray(toolArgs.types)) {
-        types.push(...toolArgs.types.map(t => String(t).toUpperCase()));
+        types.push(...toolArgs.types.map((t) => String(t).toUpperCase()));
     }
-    if (typeof toolArgs.workItemType === "string") {
+    if (typeof toolArgs.workItemType === 'string') {
         types.push(toolArgs.workItemType.toUpperCase());
     }
-    if (typeof toolArgs.type === "string") {
+    if (typeof toolArgs.type === 'string') {
         types.push(toolArgs.type.toUpperCase());
     }
     return types;
@@ -324,15 +326,15 @@ function createRestrictionInfo(feature, currentTier) {
 }
 function normalizeTier(tier) {
     const lower = tier.toLowerCase();
-    if (lower === "ultimate" || lower === "gold")
-        return "Ultimate";
-    if (lower === "premium" || lower === "silver")
-        return "Premium";
-    return "Free";
+    if (lower === 'ultimate' || lower === 'gold')
+        return 'Ultimate';
+    if (lower === 'premium' || lower === 'silver')
+        return 'Premium';
+    return 'Free';
 }
 function handleGitLabError(error, tool, action, toolArgs) {
     const { status, message, error: errorMsg, error_description } = error;
-    const rawMessage = message ?? errorMsg ?? error_description ?? "Unknown error";
+    const rawMessage = message ?? errorMsg ?? error_description ?? 'Unknown error';
     if (status === 403) {
         const tierRestriction = detectTierRestriction(tool, action, toolArgs);
         if (tierRestriction) {
@@ -345,39 +347,39 @@ function handleGitLabError(error, tool, action, toolArgs) {
     }
     if (status === 429) {
         return {
-            error_code: "RATE_LIMITED",
+            error_code: 'RATE_LIMITED',
             tool,
             action,
             http_status: status,
-            message: "Rate limit exceeded. Please wait before retrying.",
-            suggested_fix: "Wait a few minutes and try again, or reduce request frequency",
+            message: 'Rate limit exceeded. Please wait before retrying.',
+            suggested_fix: 'Wait a few minutes and try again, or reduce request frequency',
             gitlab_error: rawMessage,
         };
     }
     if (status >= 500) {
         return {
-            error_code: "SERVER_ERROR",
+            error_code: 'SERVER_ERROR',
             tool,
             action,
             http_status: status,
-            message: "GitLab server error. The service may be temporarily unavailable.",
-            suggested_fix: "Wait and retry. If the problem persists, check GitLab status page.",
+            message: 'GitLab server error. The service may be temporarily unavailable.',
+            suggested_fix: 'Wait and retry. If the problem persists, check GitLab status page.',
             gitlab_error: rawMessage,
         };
     }
     return {
-        error_code: "API_ERROR",
+        error_code: 'API_ERROR',
         tool,
         action,
         http_status: status,
         message: rawMessage,
-        suggested_fix: "Check the GitLab API documentation for this endpoint",
+        suggested_fix: 'Check the GitLab API documentation for this endpoint',
         gitlab_error: rawMessage,
     };
 }
 function createTierRestrictedError(tool, action, status, restriction) {
     return {
-        error_code: "TIER_RESTRICTED",
+        error_code: 'TIER_RESTRICTED',
         tool,
         action,
         http_status: status,
@@ -390,16 +392,16 @@ function createTierRestrictedError(tool, action, status, restriction) {
             : `Upgrade to GitLab ${restriction.requiredTier} to access this feature`,
         alternatives: restriction.alternatives.length > 0 ? restriction.alternatives : undefined,
         docs_url: restriction.docsUrl,
-        upgrade_url: "https://about.gitlab.com/pricing/",
+        upgrade_url: 'https://about.gitlab.com/pricing/',
     };
 }
 function createPermissionDeniedError(tool, action, status, rawMessage) {
-    const baseSuggestedFix = "Check your access level for this project/group. Reporter access or higher may be required.";
-    const suggestedFix = rawMessage && rawMessage !== "Unknown error" && !rawMessage.includes("403")
+    const baseSuggestedFix = 'Check your access level for this project/group. Reporter access or higher may be required.';
+    const suggestedFix = rawMessage && rawMessage !== 'Unknown error' && !rawMessage.includes('403')
         ? `${baseSuggestedFix} GitLab message: ${rawMessage}`
         : baseSuggestedFix;
     return {
-        error_code: "PERMISSION_DENIED",
+        error_code: 'PERMISSION_DENIED',
         tool,
         action,
         http_status: status,
@@ -407,9 +409,9 @@ function createPermissionDeniedError(tool, action, status, rawMessage) {
         suggested_fix: suggestedFix,
         alternatives: [
             {
-                action: "Verify your access level",
-                description: "Check your role in the project settings or contact a project maintainer",
-                available_on: "Free",
+                action: 'Verify your access level',
+                description: 'Check your role in the project settings or contact a project maintainer',
+                available_on: 'Free',
             },
         ],
     };
@@ -418,23 +420,23 @@ function createNotFoundError(tool, action, status, rawMessage) {
     let resourceType;
     let resourceId;
     const lowerMessage = rawMessage.toLowerCase();
-    if (lowerMessage.includes("project")) {
-        resourceType = "project";
+    if (lowerMessage.includes('project')) {
+        resourceType = 'project';
     }
-    else if (lowerMessage.includes("merge request") || lowerMessage.includes("mr")) {
-        resourceType = "merge_request";
+    else if (lowerMessage.includes('merge request') || lowerMessage.includes('mr')) {
+        resourceType = 'merge_request';
     }
-    else if (lowerMessage.includes("issue")) {
-        resourceType = "issue";
+    else if (lowerMessage.includes('issue')) {
+        resourceType = 'issue';
     }
-    else if (lowerMessage.includes("pipeline")) {
-        resourceType = "pipeline";
+    else if (lowerMessage.includes('pipeline')) {
+        resourceType = 'pipeline';
     }
-    else if (lowerMessage.includes("branch")) {
-        resourceType = "branch";
+    else if (lowerMessage.includes('branch')) {
+        resourceType = 'branch';
     }
-    else if (lowerMessage.includes("user")) {
-        resourceType = "user";
+    else if (lowerMessage.includes('user')) {
+        resourceType = 'user';
     }
     const pathMatch = rawMessage.match(/['"]([a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)+)['"]/);
     if (pathMatch) {
@@ -453,40 +455,40 @@ function createNotFoundError(tool, action, status, rawMessage) {
         }
     }
     return {
-        error_code: "NOT_FOUND",
+        error_code: 'NOT_FOUND',
         tool,
         action,
         http_status: status,
         message: "Resource not found or you don't have access to it",
-        suggested_fix: "Verify the ID/path is correct and you have at least Reporter access to the project",
+        suggested_fix: 'Verify the ID/path is correct and you have at least Reporter access to the project',
         resource_type: resourceType,
         resource_id: resourceId,
     };
 }
 function createMissingFieldsError(tool, action, missingFields, actionRequiredFields) {
     return {
-        error_code: "MISSING_REQUIRED_FIELD",
+        error_code: 'MISSING_REQUIRED_FIELD',
         tool,
         action,
-        message: `Missing required field(s): ${missingFields.join(", ")}`,
+        message: `Missing required field(s): ${missingFields.join(', ')}`,
         missing_fields: missingFields,
-        suggested_fix: `Add required fields: ${missingFields.join(", ")}`,
+        suggested_fix: `Add required fields: ${missingFields.join(', ')}`,
         action_required_fields: actionRequiredFields,
     };
 }
 function createInvalidActionError(tool, action, validActions) {
     return {
-        error_code: "INVALID_ACTION",
+        error_code: 'INVALID_ACTION',
         tool,
         action,
-        message: `Invalid action '${action}'. Valid actions are: ${validActions.join(", ")}`,
-        suggested_fix: `Use one of the valid actions: ${validActions.join(", ")}`,
+        message: `Invalid action '${action}'. Valid actions are: ${validActions.join(', ')}`,
+        suggested_fix: `Use one of the valid actions: ${validActions.join(', ')}`,
         valid_actions: validActions,
     };
 }
 function createTypeMismatchError(tool, action, field, expected, received) {
     return {
-        error_code: "TYPE_MISMATCH",
+        error_code: 'TYPE_MISMATCH',
         tool,
         action,
         message: `Type mismatch for field '${field}': expected ${expected}, got ${received}`,
@@ -496,19 +498,19 @@ function createTypeMismatchError(tool, action, field, expected, received) {
 }
 function createValidationError(tool, action, zodMessage) {
     return {
-        error_code: "VALIDATION_ERROR",
+        error_code: 'VALIDATION_ERROR',
         tool,
         action,
         message: zodMessage,
-        suggested_fix: "Check the tool documentation for correct parameter format",
+        suggested_fix: 'Check the tool documentation for correct parameter format',
     };
 }
 function createTimeoutError(tool, action, timeoutMs, retryable = false) {
     const retryHint = retryable
-        ? " This is a read-only operation - you can safely retry."
-        : " This is a write operation - check if it completed before retrying.";
+        ? ' This is a read-only operation - you can safely retry.'
+        : ' This is a write operation - check if it completed before retrying.';
     return {
-        error_code: "TIMEOUT",
+        error_code: 'TIMEOUT',
         tool,
         action,
         timeout_ms: timeoutMs,
@@ -536,7 +538,7 @@ function createVersionRestrictedError(tool, action, widget, parameter, requiredV
         suggestedFix = `Upgrade GitLab to version ${requiredVersion} or higher to use the '${parameter}' parameter`;
     }
     return {
-        error_code: "VERSION_RESTRICTED",
+        error_code: 'VERSION_RESTRICTED',
         tool,
         action,
         widget,
@@ -547,7 +549,7 @@ function createVersionRestrictedError(tool, action, widget, parameter, requiredV
         current_tier: isTierInsufficient ? currentTier : undefined,
         message,
         suggested_fix: suggestedFix,
-        docs_url: "https://docs.gitlab.com/ee/user/project/work_items/",
+        docs_url: 'https://docs.gitlab.com/ee/user/project/work_items/',
     };
 }
 function parseGitLabApiError(errorMessage) {
@@ -555,8 +557,8 @@ function parseGitLabApiError(errorMessage) {
     if (!match)
         return null;
     const status = parseInt(match[1], 10);
-    const statusText = match[2]?.trim() ?? "";
-    const details = match[3]?.trim() ?? "";
+    const statusText = match[2]?.trim() ?? '';
+    const details = match[3]?.trim() ?? '';
     let message;
     if (statusText && details) {
         message = `${status} ${statusText} - ${details}`;
@@ -580,7 +582,7 @@ class StructuredToolError extends Error {
     structuredError;
     constructor(structuredError) {
         super(structuredError.message);
-        this.name = "StructuredToolError";
+        this.name = 'StructuredToolError';
         this.structuredError = structuredError;
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, StructuredToolError);
@@ -594,4 +596,87 @@ exports.StructuredToolError = StructuredToolError;
 function isStructuredToolError(error) {
     return error instanceof StructuredToolError;
 }
+const TRANSIENT_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ECONNABORTED',
+    'ETIMEDOUT',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'EAI_AGAIN',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'UND_ERR_SOCKET',
+]);
+function classifyError(error) {
+    if (!(error instanceof Error)) {
+        return 'permanent';
+    }
+    const message = error.message.toLowerCase();
+    const code = error.code;
+    const causeCode = error.cause?.code;
+    const effectiveCode = code ?? causeCode;
+    if (effectiveCode && TRANSIENT_ERROR_CODES.has(effectiveCode)) {
+        return 'transient';
+    }
+    const parsed = parseGitLabApiError(error.message);
+    if (parsed) {
+        const { status } = parsed;
+        if (status === 401) {
+            return 'auth';
+        }
+        if (status === 403) {
+            return 'permanent';
+        }
+        if (status === 408 || status === 429 || status >= 500) {
+            return 'transient';
+        }
+        return 'permanent';
+    }
+    if (message.includes('timed out') ||
+        message.includes('request timeout') ||
+        message.includes('connect timeout') ||
+        message.includes('initialization timeout') ||
+        message.includes('socket hang up') ||
+        message.includes('network error') ||
+        message.includes('health check failed') ||
+        message.includes('econnrefused') ||
+        message.includes('econnreset')) {
+        return 'transient';
+    }
+    return 'permanent';
+}
+function createConnectionFailedError(toolName, action, instanceUrl, connectionState) {
+    const reconnecting = connectionState === 'connecting';
+    const autoRetryEnabled = connectionState !== 'failed';
+    let message;
+    if (connectionState === 'failed') {
+        message =
+            `GitLab instance ${instanceUrl} connection failed due to a permanent authentication, ` +
+                `permission, or configuration error. Automatic reconnection is disabled.`;
+    }
+    else if (connectionState === 'connecting') {
+        message = `GitLab instance ${instanceUrl} is not ready yet. A connection attempt is in progress.`;
+    }
+    else {
+        message = `GitLab instance ${instanceUrl} is currently unreachable. Connection will be retried automatically.`;
+    }
+    const suggestedFix = connectionState === 'failed'
+        ? 'Check authentication/authorization, permissions or tier access, and the configured GitLab instance URL. ' +
+            "Use manage_context with action 'whoami' to check connection status."
+        : 'Check network connectivity, VPN status, or GitLab instance availability. ' +
+            "Use manage_context with action 'whoami' to check connection status.";
+    return {
+        error_code: 'CONNECTION_FAILED',
+        tool: toolName,
+        action,
+        instance_url: instanceUrl,
+        reconnecting,
+        auto_retry_enabled: autoRetryEnabled,
+        message,
+        suggested_fix: suggestedFix,
+    };
+}
 //# sourceMappingURL=error-handler.js.map