interface GitLabInstanceConfig {
  baseUrl: string;
  oauthClientId?: string;
  oauthClientSecret?: string;
  maxConcurrentRequests?: number;  // Default: 100
  requestQueueSize?: number;       // Default: 500
  label?: string;                  // Human-readable name for UI
}

// Instance-level cache: version + schema only, NO TIER
interface InstanceIntrospection {
  version: string;
  isSaaS: boolean;                 // gitlab.com = true
  schemaInfo: SchemaInfo;          // GraphQL types, widgets
  detectedAt: Date;
}

interface GitLabInstance extends GitLabInstanceConfig {
  // Runtime state
  activeRequests: number;
  requestQueue: Array<QueuedRequest>;
  introspection: InstanceIntrospection | null;
  connectionStatus: 'healthy' | 'degraded' | 'offline';
  lastHealthCheck: Date | null;
}

class InstanceRegistry {
  private instances = new Map<string, GitLabInstance>();
  
  register(config: GitLabInstanceConfig): void;
  get(baseUrl: string): GitLabInstance | undefined;
  list(): GitLabInstance[];
  unregister(baseUrl: string): boolean;
  
  // Request slot management (rate limiting)
  async acquireSlot(baseUrl: string): Promise<ReleaseFunction>;
  
  // Instance-level introspection (version + schema, NO tier)
  async getIntrospection(baseUrl: string, token: string): Promise<InstanceIntrospection>;
}

interface TokenContextData {
  token: string;
  apiUrl: string;              // GitLab instance URL
  instanceLabel?: string;      // Human-readable instance name
  // NO tier here - tier is per-namespace!
}

interface NamespaceTierInfo {
  tier: 'free' | 'premium' | 'ultimate';
  features: Record<string, boolean>;
  cachedAt: Date;
}

interface OAuthSession {
  // Existing fields...
  gitlabApiUrl: string;
  instanceLabel?: string;
  scopes: string[];
  
  // Namespace tier cache (key: namespacePath)
  namespaceTierCache: Map<string, NamespaceTierInfo>;
}

// Helper to get/cache namespace tier
async function getNamespaceTier(
  session: OAuthSession, 
  namespacePath: string
): Promise<NamespaceTierInfo> {
  const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
  
  const cached = session.namespaceTierCache.get(namespacePath);
  if (cached && Date.now() - cached.cachedAt.getTime() < CACHE_TTL) {
    return cached;
  }
  
  // Query GitLab for namespace tier
  const tierInfo = await queryNamespaceTier(namespacePath);
  session.namespaceTierCache.set(namespacePath, tierInfo);
  return tierInfo;
}

// Query namespace tier via GraphQL
const NAMESPACE_TIER_QUERY = `
  query GetNamespaceTier($fullPath: ID!) {
    namespace(fullPath: $fullPath) {
      id
      fullPath
      
      # For groups - check plan directly
      ... on Group {
        plan
        actualPlanName  # "free", "premium", "ultimate"
      }
      
      # For projects - check parent group's plan
      ... on Project {
        group {
          plan
          actualPlanName
        }
      }
    }
  }
`;

async function queryNamespaceTier(namespacePath: string): Promise<NamespaceTierInfo> {
  const result = await graphqlRequest(NAMESPACE_TIER_QUERY, { fullPath: namespacePath });
  
  // Extract tier from response
  const planName = result.namespace?.actualPlanName 
    || result.namespace?.group?.actualPlanName 
    || 'free';
  
  return {
    tier: normalizeTier(planName),
    features: getFeaturesForTier(planName),
    cachedAt: new Date(),
  };
}

function getFeaturesForTier(tier: string): Record<string, boolean> {
  const tiers = {
    free: {
      epics: false,
      iterations: false,
      roadmaps: false,
      // ... etc
    },
    premium: {
      epics: true,
      iterations: true,
      roadmaps: true,
      // ... etc
    },
    ultimate: {
      epics: true,
      iterations: true,
      roadmaps: true,
      securityDashboard: true,
      // ... etc
    },
  };
  return tiers[tier] || tiers.free;
}

export async function enhancedFetch(
  urlOrPath: string,
  options?: EnhancedFetchOptions
): Promise<Response> {
  const context = getTokenContext();
  
  // Determine base URL: context > global > error
  const baseUrl = context?.apiUrl ?? GITLAB_BASE_URL;
  if (!baseUrl) {
    throw new Error('No GitLab API URL available');
  }
  
  // Acquire rate limit slot before request
  const registry = InstanceRegistry.getInstance();
  const release = await registry.acquireSlot(baseUrl);
  
  try {
    const url = urlOrPath.startsWith('http') 
      ? urlOrPath 
      : `${baseUrl}${urlOrPath}`;
    
    // ... rest of fetch logic
  } finally {
    release();
  }
}

// In work items handler
async function handleCreateEpic(args: CreateEpicArgs, session: OAuthSession) {
  // Get tier for target namespace
  const tierInfo = await getNamespaceTier(session, args.groupPath);
  
  // Check if epics are available
  if (!tierInfo.features.epics) {
    throw new Error(
      `Epics require GitLab Premium or Ultimate. ` +
      `Namespace "${args.groupPath}" is on ${tierInfo.tier} tier.`
    );
  }
  
  // Proceed with epic creation...
}

const manageWorkItemsTool = {
  name: 'manage_work_items',
  description: `
    Create and manage GitLab work items (issues, tasks, epics, etc.).
    
    Note: Some work item types require specific GitLab tiers:
    - Issues, Tasks: Available on all tiers
    - Epics: Requires Premium or Ultimate
    - OKRs: Requires Ultimate
    
    Tier is determined per-namespace (group/project), not globally.
  `,
  // ...
};

class InstanceRateLimiter {
  private activeRequests = 0;
  private queue: Array<{
    resolve: (release: () => void) => void;
    reject: (error: Error) => void;
    enqueuedAt: number;
  }> = [];
  
  constructor(
    private maxConcurrent: number,
    private queueSize: number,
    private queueTimeout: number
  ) {}
  
  async acquire(): Promise<() => void> {
    if (this.activeRequests < this.maxConcurrent) {
      this.activeRequests++;
      return () => this.release();
    }
    
    if (this.queue.length >= this.queueSize) {
      throw new Error(
        `Rate limit exceeded: ${this.activeRequests} active, ` +
        `${this.queue.length} queued (max: ${this.queueSize})`
      );
    }
    
    return new Promise((resolve, reject) => {
      const entry = { resolve, reject, enqueuedAt: Date.now() };
      this.queue.push(entry);
      
      setTimeout(() => {
        const idx = this.queue.indexOf(entry);
        if (idx !== -1) {
          this.queue.splice(idx, 1);
          reject(new Error(
            `Request queued for ${this.queueTimeout}ms, timing out`
          ));
        }
      }, this.queueTimeout);
    });
  }
  
  private release(): void {
    this.activeRequests--;
    
    if (this.queue.length > 0 && this.activeRequests < this.maxConcurrent) {
      const next = this.queue.shift()!;
      this.activeRequests++;
      next.resolve(() => this.release());
    }
  }
}

interface RateLimitMetrics {
  instanceUrl: string;
  activeRequests: number;
  maxConcurrent: number;
  queuedRequests: number;
  queueSize: number;
  requestsTotal: number;
  requestsQueued: number;
  requestsRejected: number;
  avgQueueWaitMs: number;
}

interface OAuthState {
  selectedInstance: string;
  // ... other fields
}

async function handleOAuthCallback(code: string, state: OAuthState) {
  const session = await createSession({
    gitlabApiUrl: state.selectedInstance,
    namespaceTierCache: new Map(), // Empty, will populate on demand
    // ... other fields
  });
}

// In manage_context handler
async function handleSwitchContext(newInstanceUrl: string, session: OAuthSession) {
  // 1. Validate instance is registered
  const registry = InstanceRegistry.getInstance();
  const instance = registry.get(newInstanceUrl);
  if (!instance) {
    throw new Error(`Instance not configured: ${newInstanceUrl}`);
  }
  
  // 2. In OAuth mode, block switching (requires re-auth)
  if (isOAuthEnabled()) {
    throw new Error(
      `Cannot switch instances in OAuth mode. ` +
      `Please re-authenticate with ${instance.label || newInstanceUrl}`
    );
  }
  
  // 3. Get/refresh introspection for new instance
  const introspection = await registry.getIntrospection(newInstanceUrl, session.token);
  
  // 4. Update session
  session.gitlabApiUrl = newInstanceUrl;
  session.instanceLabel = instance.label;
  
  // 5. Clear namespace tier cache (invalid for new instance)
  session.namespaceTierCache.clear();
  
  // 6. Re-validate and filter tools based on new schema
  const toolRegistry = ToolRegistry.getInstance();
  const validationResult = await toolRegistry.revalidateForSchema(introspection.schemaInfo);
  
  return {
    success: true,
    instance: newInstanceUrl,
    label: instance.label,
    version: introspection.version,
    availableTools: validationResult.availableCount,
    disabledTools: validationResult.disabledTools,
  };
}

class ToolRegistry {
  async revalidateForSchema(schemaInfo: SchemaInfo): Promise<ValidationResult> {
    const disabledTools: string[] = [];
    
    for (const tool of this.tools.values()) {
      // Check if tool's required GraphQL types exist in schema
      const isValid = this.validateToolAgainstSchema(tool, schemaInfo);
      tool.setAvailable(isValid);
      
      if (!isValid) {
        disabledTools.push(tool.name);
        logInfo(`Tool ${tool.name} disabled: required types not in schema`, {
          requiredTypes: tool.requiredGraphQLTypes,
          instanceVersion: schemaInfo.version,
        });
      }
    }
    
    return {
      availableCount: this.tools.size - disabledTools.length,
      disabledTools,
    };
  }
  
  private validateToolAgainstSchema(tool: Tool, schema: SchemaInfo): boolean {
    // Check required types
    for (const typeName of tool.requiredGraphQLTypes || []) {
      if (!schema.typeDefinitions.has(typeName)) {
        return false;
      }
    }
    
    // Check required widgets (for work items)
    for (const widgetType of tool.requiredWidgets || []) {
      if (!schema.workItemWidgetTypes.includes(widgetType)) {
        return false;
      }
    }
    
    return true;
  }
}

// Response format for context switch
{
  "success": true,
  "instance": "https://gl.old.example.com",
  "version": "15.0.0",
  "availableTools": 38,
  "disabledTools": [
    "manage_work_items",  // Work Items API not available in v15
    "browse_iterations"   // Iterations require newer version
  ],
  "message": "Switched to gl.old.example.com (v15.0.0). 6 tools disabled due to schema differences."
}

describe('Multi-Instance Federation', () => {
  describe('InstanceRegistry', () => {
    it('should register multiple instances from config file');
    it('should register instances from env var array');
    it('should fall back to GITLAB_BASE_URL for single instance');
    it('should validate instance URLs');
    it('should handle duplicate instance URLs');
  });

  describe('Caching Layers', () => {
    describe('Instance-Level Cache', () => {
      it('should cache version and schema per instance');
      it('should NOT cache tier at instance level');
      it('should share instance cache between sessions');
      it('should expire instance cache after TTL');
    });
    
    describe('Namespace-Level Cache', () => {
      it('should cache tier per namespace within session');
      it('should NOT share namespace tier between sessions');
      it('should expire namespace tier cache after TTL');
      it('should query tier on cache miss');
    });
  });

  describe('Tier Detection', () => {
    it('should detect Free tier for free namespace');
    it('should detect Premium tier for premium namespace');
    it('should detect Ultimate tier for ultimate namespace');
    it('should handle project tier via parent group');
    it('should return correct features for each tier');
  });

  describe('Rate Limiting', () => {
    it('should limit concurrent requests per instance');
    it('should queue requests when at capacity');
    it('should timeout queued requests after configured duration');
    it('should reject requests when queue is full');
    it('should release slots on request completion');
    it('should release slots on request failure');
    it('should track rate limit metrics');
  });

  describe('OAuth Flow with Instance Selection', () => {
    it('should include instance URL in OAuth state');
    it('should restore instance from OAuth callback state');
    it('should create session with correct gitlabApiUrl');
    it('should initialize empty namespace tier cache');
    it('should reject OAuth for unconfigured instances');
  });

  describe('Context Switching', () => {
    it('should block instance switching in OAuth mode');
    it('should allow instance switching in static token mode');
    it('should re-introspect on instance switch');
    it('should clear namespace tier cache on switch');
    it('should re-validate tools against new schema');
    it('should report disabled tools after switch');
    it('should use correct instance URL after switch');
  });

  describe('Cross-Session Isolation', () => {
    it('should isolate token context between sessions');
    it('should use correct instance URL in enhancedFetch');
    it('should NOT share namespace tier cache between sessions');
  });

  describe('Configuration Loading', () => {
    it('should load YAML config file');
    it('should load JSON config file');
    it('should parse bash array syntax');
    it('should apply defaults to all instances');
    it('should override defaults with instance-specific config');
  });
  
  describe('Feature Availability', () => {
    it('should block epic creation on Free tier namespace');
    it('should allow epic creation on Premium tier namespace');
    it('should provide helpful error message with tier info');
  });
});

interface MultiInstanceTestContext {
  instances: {
    primary: TestGitLabInstance;
    secondary?: TestGitLabInstance;
  };
  sessions: Map<string, TestSession>;
  // Test namespaces with known tiers
  namespaces: {
    free: string;      // e.g., "test/free-group"
    premium: string;   // e.g., "test/premium-group"  
    ultimate: string;  // e.g., "test/ultimate-group"
  };
}

beforeAll(async () => {
  const registry = InstanceRegistry.getInstance();
  registry.register({
    baseUrl: process.env.GITLAB_API_URL!,
    label: 'Primary Test Instance',
    maxConcurrentRequests: 10,
  });
  
  if (process.env.GITLAB_SECONDARY_URL) {
    registry.register({
      baseUrl: process.env.GITLAB_SECONDARY_URL,
      label: 'Secondary Test Instance',
      maxConcurrentRequests: 5,
    });
  }
});

afterAll(async () => {
  const sessionManager = SessionManager.getInstance();
  await sessionManager.cleanupAllSessions();
});