interface ActionValidationError {
  error_code: "MISSING_REQUIRED_FIELD" | "INVALID_ACTION" | "FIELD_NOT_ALLOWED" | "TYPE_MISMATCH";
  tool: string;
  action: string;
  missing_fields?: string[];
  invalid_fields?: Array<{
    field: string;
    expected: string;
    received: string;
  }>;
  suggested_fix: string;
  valid_actions?: string[];
  action_required_fields?: Record<string, string[]>;
}

// Example
{
  "error_code": "MISSING_REQUIRED_FIELD",
  "tool": "manage_merge_request",
  "action": "create",
  "missing_fields": ["project_id", "source_branch", "target_branch", "title"],
  "suggested_fix": "Add required fields: project_id, source_branch, target_branch, title",
  "action_required_fields": {
    "create": ["project_id", "source_branch", "target_branch", "title"],
    "update": ["project_id", "merge_request_iid"],
    "merge": ["project_id", "merge_request_iid"]
  }
}

interface TierRestrictedError {
  error_code: "TIER_RESTRICTED" | "FEATURE_UNAVAILABLE" | "PERMISSION_DENIED";
  tool: string;
  action: string;
  http_status: number;

  // Tier information
  tier_required: "Free" | "Premium" | "Ultimate";
  current_tier?: string;  // If detectable
  feature_name: string;

  // Actionable guidance
  message: string;
  alternatives?: Array<{
    action: string;
    description: string;
    available_on: string;
  }>;
  docs_url?: string;
  upgrade_url?: string;
}

// src/utils/tier-features.ts

interface TierFeature {
  name: string;
  tier: "Free" | "Premium" | "Ultimate";
  tools: string[];
  alternatives?: string[];
  docs: string;
}

export const TIER_FEATURES: Record<string, TierFeature> = {
  // Premium Features
  protected_branches_api: {
    name: "Protected Branches API",
    tier: "Premium",
    tools: ["browse_protected_branches", "manage_protected_branch"],
    alternatives: ["Configure via UI", "Use browse_commits to check branch"],
    docs: "https://docs.gitlab.com/ee/api/protected_branches.html"
  },
  merge_request_approvals: {
    name: "Merge Request Approvals",
    tier: "Premium",
    tools: ["manage_merge_request:approve"],
    alternatives: ["Use comments for informal approval"],
    docs: "https://docs.gitlab.com/ee/user/project/merge_requests/approvals/"
  },
  group_webhooks: {
    name: "Group Webhooks",
    tier: "Premium",
    tools: ["list_webhooks:group", "manage_webhook:group"],
    alternatives: ["Use project-level webhooks (Free)"],
    docs: "https://docs.gitlab.com/ee/user/project/integrations/webhooks.html"
  },

  // Ultimate Features
  code_owners: {
    name: "Code Owners",
    tier: "Ultimate",
    tools: ["browse_code_owners"],
    alternatives: ["Read CODEOWNERS file via browse_files"],
    docs: "https://docs.gitlab.com/ee/user/project/codeowners/"
  },
  security_dashboard: {
    name: "Security Dashboard",
    tier: "Ultimate",
    tools: ["browse_vulnerabilities"],
    docs: "https://docs.gitlab.com/ee/user/application_security/security_dashboard/"
  },
  epic_boards: {
    name: "Epic Boards",
    tier: "Ultimate",
    tools: ["browse_epics:board"],
    alternatives: ["Use issue boards (Free)", "List epics without board view"],
    docs: "https://docs.gitlab.com/ee/user/group/epics/"
  }
};

// src/utils/error-handler.ts

import { TIER_FEATURES } from './tier-features';

interface GitLabError {
  status: number;
  message?: string;
  error?: string;
}

export function handleGitLabError(
  error: GitLabError,
  tool: string,
  action: string
): StructuredError {

  // Check if this is a tier-restricted feature
  const tierFeature = findTierFeature(tool, action);

  if (error.status === 403 && tierFeature) {
    return {
      error_code: "TIER_RESTRICTED",
      tool,
      action,
      http_status: 403,
      tier_required: tierFeature.tier,
      feature_name: tierFeature.name,
      message: `${tierFeature.name} requires GitLab ${tierFeature.tier} or higher`,
      alternatives: tierFeature.alternatives?.map(alt => ({
        action: alt,
        description: getAlternativeDescription(alt),
        available_on: "Free"
      })),
      docs_url: tierFeature.docs,
      upgrade_url: "https://about.gitlab.com/pricing/"
    };
  }

  if (error.status === 403) {
    return {
      error_code: "PERMISSION_DENIED",
      tool,
      action,
      http_status: 403,
      message: "You don't have permission for this action",
      suggested_fix: "Check your access level for this project/group",
      alternatives: [
        {
          action: "Verify access",
          description: "Use get_users to check your role in the project",
          available_on: "Free"
        }
      ]
    };
  }

  if (error.status === 404) {
    return {
      error_code: "NOT_FOUND",
      tool,
      action,
      http_status: 404,
      message: "Resource not found or you don't have access",
      suggested_fix: "Verify the ID/path is correct and you have at least Reporter access"
    };
  }

  // Generic error
  return {
    error_code: "API_ERROR",
    tool,
    action,
    http_status: error.status,
    message: error.message || error.error || "Unknown error",
    suggested_fix: "Check the GitLab API documentation for this endpoint"
  };
}

// In registry handlers
try {
  return await gitlab.get(path, options);
} catch (error) {
  if (error instanceof GitLabApiError) {
    throw new StructuredToolError(
      handleGitLabError(error, toolName, action)
    );
  }
  throw error;
}

// Already have in EnhancedToolDefinition
interface EnhancedToolDefinition {
  // ...
  tier?: "Free" | "Premium" | "Ultimate";
  gate?: { envVar: string; defaultValue: boolean };
}

// Use tier info in error handling
function findTierFeature(tool: string, action: string): TierFeature | null {
  const toolDef = getToolDefinition(tool);
  if (toolDef?.tier && toolDef.tier !== "Free") {
    return {
      name: toolDef.description.split('.')[0],
      tier: toolDef.tier,
      tools: [tool],
      docs: `https://docs.gitlab.com/ee/api/`
    };
  }
  // Check TIER_FEATURES map
  return Object.values(TIER_FEATURES).find(f =>
    f.tools.some(t => t === tool || t === `${tool}:${action}`)
  ) || null;
}