roles.ts

import { ROLE_IDS, type RoleId } from './roleIds';

/**
 * GitHub team configuration
 */
export interface GitHubConfig {
  /** Team name (usually matches role ID) */
  team: string;
  /** Parent team role ID */
  parent?: RoleId;
}

/**
 * Discord role configuration
 */
export interface DiscordConfig {
  /** Display name in Discord (can have spaces) */
  role: string;
}

/**
 * Google Workspace group configuration
 */
export interface GoogleConfig {
  /** Group name (used as prefix for @modelcontextprotocol.io email) */
  group: string;
  /** If true, accepts emails from anyone including external users */
  isEmailGroup?: boolean;
  /**
   * Opt-in for groups that intentionally include non-@modelcontextprotocol.io
   * members. Defaults to false. Must stay declared on the GroupSettings
   * resource: the provider resets an omitted field to false on every apply,
   * after which Google silently purges external members (#133 incident).
   */
  allowExternalMembers?: boolean;
}

/**
 * Role definition with platform-specific configurations.
 * A role only exists on platforms where it has a config key.
 */
export interface Role {
  id: RoleId;
  description: string;
  github?: GitHubConfig;
  discord?: DiscordConfig;
  google?: GoogleConfig;
  /**
   * If true, members of this role — directly, or via a role that nests under
   * it through github.parent (child team members are members of the parent
   * team on GitHub) — may opt in to a Google Workspace user account by adding
   * firstName/lastName/googleEmailPrefix to their entry in users.ts.
   */
  provisionUser?: boolean;
  /**
   * Roles that are implied for Discord membership.
   * If a user has this role, they automatically get the implied roles' Discord roles too.
   * This is separate from GitHub parent relationships and allows Discord-specific hierarchy.
   */
  discordImplies?: readonly RoleId[];
}

/**
 * All roles in the MCP organization.
 * Each role specifies which platforms it exists on via presence of config keys.
 */
export const ROLES: readonly Role[] = [
  // ===================
  // Organization Structure
  // ===================
  {
    id: ROLE_IDS.STEERING_COMMITTEE,
    description: 'MCP Steering Committee',
    github: { team: 'steering-committee' },
    // No discord - this is a GitHub-only organizational container
  },
  {
    id: ROLE_IDS.ADMINISTRATORS,
    description: 'Discord server administrators',
    discord: { role: 'administrators (synced)' },
    // Discord only - no GitHub equivalent
  },
  {
    id: ROLE_IDS.COMMUNITY_MANAGERS,
    description: 'Discord community managers',
    discord: { role: 'community managers (synced)' },
    // Discord only - no GitHub equivalent
  },
  {
    id: ROLE_IDS.LEAD_MAINTAINERS,
    description: 'Lead core maintainers',
    github: { team: 'lead-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    discord: { role: 'lead maintainers (synced)' },
    google: { group: 'lead-maintainers' },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.CORE_MAINTAINERS,
    description: 'Core maintainers',
    github: { team: 'core-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    discord: { role: 'core maintainers (synced)' },
    google: { group: 'core-maintainers' },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.MODERATORS,
    description: 'Community moderators',
    github: { team: 'moderators', parent: ROLE_IDS.STEERING_COMMITTEE },
    discord: { role: 'community moderators (synced)' },
    google: { group: 'moderators' },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.SECURITY_MANAGERS,
    description: 'Organization security managers (security_manager org role via orgRoles.ts)',
    github: { team: 'security-managers' },
    // GitHub only - grants org-wide visibility into security alerts and draft advisories
  },
  {
    id: ROLE_IDS.SECURITY_TEAM,
    description: 'MCP Security Team: SDK security leads who coordinate advisories across SDKs',
    // Grants sign-in to securityroom.modelcontextprotocol.io via the Cloudflare Access
    // policy in accessPolicies.ts. Cloudflare matches direct team membership only, so
    // SDK security leads are added here explicitly rather than via sdk-maintainers.
    // No parent team: must not inherit steering-committee repo permissions.
    github: { team: 'security-team' },
    // GitHub only - grants no repository permissions by itself
  },

  // ===================
  // Maintainer Groups
  // ===================
  {
    id: ROLE_IDS.MAINTAINERS,
    description: 'General maintainers',
    // No parent team: must not inherit steering-committee repo permissions
    github: { team: 'maintainers' },
    discord: { role: 'maintainers (synced)' },
    // GWS user accounts are opt-in: maintainers add firstName/lastName/googleEmailPrefix
    // to their entry in users.ts via PR to get an @modelcontextprotocol.io account
    google: { group: 'maintainers', allowExternalMembers: true },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.CONFORMANCE_AUTH,
    description: 'Conformance authorization-server code owners',
    github: { team: 'conformance-auth' },
    // GitHub only - for CODEOWNERS in the conformance repo
  },
  {
    id: ROLE_IDS.DOCS_MAINTAINERS,
    description: 'MCP docs maintainers',
    github: { team: 'docs-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    // No discord role for docs maintainers
    provisionUser: true,
  },
  {
    id: ROLE_IDS.INSPECTOR_MAINTAINERS,
    description: 'MCP Inspector maintainers',
    github: { team: 'inspector-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    discord: { role: 'inspector maintainers (synced)' },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.MCPB_MAINTAINERS,
    description: 'MCPB (Model Context Protocol Bundle) maintainers',
    github: { team: 'mcpb-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    // No discord role
    provisionUser: true,
  },
  {
    id: ROLE_IDS.REFERENCE_SERVERS_MAINTAINERS,
    description: 'Reference servers maintainers',
    github: { team: 'reference-servers-maintainers' },
    discord: { role: 'reference servers maintainers (synced)' },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.REGISTRY_MAINTAINERS,
    description: 'Official registry builders and maintainers',
    github: { team: 'registry-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'registry maintainers (synced)' },
    google: { group: 'registry-wg', allowExternalMembers: true },
    provisionUser: true,
  },
  {
    id: ROLE_IDS.REGISTRY_COLLABORATORS,
    description: 'Registry working group collaborators',
    github: { team: 'registry-collaborators', parent: ROLE_IDS.REGISTRY_MAINTAINERS },
  },
  {
    id: ROLE_IDS.USE_MCP_MAINTAINERS,
    description: 'use-mcp maintainers',
    discord: { role: 'use-mcp maintainers (synced)' },
    // Discord only
    provisionUser: true,
  },

  // ===================
  // SDK Maintainers
  // ===================
  {
    id: ROLE_IDS.SDK_MAINTAINERS,
    description: 'Authors and maintainers of official MCP SDKs',
    github: { team: 'sdk-maintainers', parent: ROLE_IDS.STEERING_COMMITTEE },
    discord: { role: 'sdk maintainers (synced)' },
    discordImplies: [ROLE_IDS.MAINTAINERS], // SDK maintainers are also general maintainers
    // Covers all SDK teams via github.parent (e.g. python-sdk, rust-sdk)
    provisionUser: true,
  },
  {
    id: ROLE_IDS.CSHARP_SDK,
    description: 'Official C# SDK maintainers',
    github: { team: 'csharp-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'c# sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.CSHARP_SDK_ADMIN,
    description: 'C# SDK repository admins',
    github: { team: 'csharp-sdk-admin', parent: ROLE_IDS.CSHARP_SDK },
    // GitHub only - for repo admin access
  },
  {
    id: ROLE_IDS.GO_SDK,
    description: 'The Go SDK Team',
    github: { team: 'go-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'go sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.JAVA_SDK,
    description: 'Official Java SDK maintainers',
    github: { team: 'java-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'java sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.KOTLIN_SDK,
    description: 'Official Kotlin SDK maintainers',
    github: { team: 'kotlin-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'kotlin sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.MCP_APPS_SDK,
    description: 'Official MCP Apps SDK maintainers',
    github: { team: 'mcp-apps-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    // No Discord channel/role yet: #mcp-apps-sdk-dev in the future
  },
  {
    id: ROLE_IDS.PHP_SDK,
    description: 'Official PHP SDK maintainers',
    github: { team: 'php-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'php sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.PYTHON_SDK,
    description: 'Official Python SDK maintainers',
    github: { team: 'python-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'python sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.PYTHON_SDK_AUTH,
    description: 'Python SDK auth code owners',
    github: { team: 'python-sdk-auth', parent: ROLE_IDS.PYTHON_SDK },
    // GitHub only - for CODEOWNERS
  },
  {
    id: ROLE_IDS.RUBY_SDK,
    description: 'Official Ruby SDK maintainers',
    github: { team: 'ruby-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'ruby sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.RUST_SDK,
    description: 'Official Rust SDK maintainers',
    github: { team: 'rust-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'rust sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.SWIFT_SDK,
    description: 'Official Swift SDK maintainers',
    github: { team: 'swift-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'swift sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.TYPESCRIPT_SDK,
    description: 'Official TypeScript SDK',
    github: { team: 'typescript-sdk', parent: ROLE_IDS.SDK_MAINTAINERS },
    discord: { role: 'typescript sdk maintainers (synced)' },
  },
  {
    id: ROLE_IDS.TYPESCRIPT_SDK_AUTH,
    description: 'Code owners for auth in Typescript SDK',
    github: { team: 'typescript-sdk-auth', parent: ROLE_IDS.TYPESCRIPT_SDK },
    // GitHub only - for CODEOWNERS
  },
  {
    id: ROLE_IDS.TYPESCRIPT_SDK_COLLABORATORS,
    description: 'TypeScript SDK collaborators',
    github: { team: 'typescript-sdk-collaborators', parent: ROLE_IDS.TYPESCRIPT_SDK },
    // GitHub only
  },

  // ===================
  // Working Groups
  // ===================
  {
    id: ROLE_IDS.WORKING_GROUPS,
    description: 'MCP Working Groups',
    github: { team: 'working-groups', parent: ROLE_IDS.STEERING_COMMITTEE },
    // No discord - organizational container
    // Covers all working groups via github.parent (e.g. transport-wg, agents-wg)
    provisionUser: true,
  },
  {
    id: ROLE_IDS.AUTH_MAINTAINERS,
    description: 'Auth Maintainers',
    github: { team: 'auth-maintainers', parent: ROLE_IDS.WORKING_GROUPS },
    // See AUTH_IG for Discord role
  },
  {
    id: ROLE_IDS.AUTH_TOOL_SCOPES_WG,
    description: 'Auth Tool Scopes Working Group',
    github: { team: 'auth-wg-tool-scopes', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'auth tool scopes working group (synced)' },
  },
  {
    id: ROLE_IDS.AUTH_FINE_GRAINED_AUTHZ_WG,
    description: 'Auth Fine-Grained Authorization Working Group',
    github: { team: 'auth-wg-fine-grained-authz', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'auth fine-grained authorization working group (synced)' },
  },
  {
    id: ROLE_IDS.TRANSPORT_WG,
    description: 'Transport Working Group',
    github: { team: 'transport-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'transports working group (synced)' },
  },
  {
    id: ROLE_IDS.TRIGGERS_EVENTS_WG,
    description: 'Triggers & Events Working Group',
    github: { team: 'triggers-events-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'triggers & events working group (synced)' },
  },
  {
    id: ROLE_IDS.MCP_APPS_WG,
    description: 'MCP Apps Working Group',
    github: { team: 'mcp-apps-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'mcp apps working group (synced)' },
  },
  {
    id: ROLE_IDS.SERVER_CARD_WG,
    description: 'Server Card Working Group',
    github: { team: 'server-card-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'server card working group (synced)' },
  },
  {
    id: ROLE_IDS.INTERCEPTORS_WG,
    description: 'Interceptors Working Group',
    github: { team: 'interceptors-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'interceptors working group (synced)' },
  },
  {
    id: ROLE_IDS.FILE_UPLOADS_WG,
    description: 'File Uploads Working Group',
    github: { team: 'file-uploads-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'file uploads working group (synced)' },
  },
  {
    id: ROLE_IDS.AGENTS_WG,
    description: 'Agents Working Group',
    github: { team: 'agents-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'agents working group (synced)' },
  },
  {
    id: ROLE_IDS.SKILLS_OVER_MCP_WG,
    description: 'Skills Over MCP Working Group',
    github: { team: 'skills-over-mcp-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'skills over mcp working group (synced)' },
  },
  {
    id: ROLE_IDS.SKILLS_OVER_MCP_WG_LEADS,
    description: 'Skills Over MCP Working Group leads',
    github: { team: 'skills-over-mcp-wg-leads', parent: ROLE_IDS.SKILLS_OVER_MCP_WG },
  },
  {
    id: ROLE_IDS.FILESYSTEMS_WG,
    description: 'Filesystems Working Group',
    github: { team: 'filesystems-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'filesystems working group (synced)' },
  },
  {
    id: ROLE_IDS.CORE_PRIMITIVE_WG,
    description: 'Core Primitive Working Group',
    github: { team: 'core-primitive-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'core primitive working group (synced)' },
  },
  {
    id: ROLE_IDS.INFRASTRUCTURE_WG,
    description: 'Infrastructure Working Group',
    github: { team: 'infrastructure-wg', parent: ROLE_IDS.WORKING_GROUPS },
    discord: { role: 'infrastructure working group (synced)' },
  },

  // ===================
  // Interest Groups
  // ===================
  {
    id: ROLE_IDS.INTEREST_GROUPS,
    description: 'Interest Groups',
    github: { team: 'interest-groups', parent: ROLE_IDS.STEERING_COMMITTEE },
    // No discord - organizational container
  },
  {
    id: ROLE_IDS.AUTH_IG,
    description: 'Auth Interest Group',
    discord: { role: 'auth interest group (synced)' },
    // Discord only - separate from AUTH_MAINTAINERS which is GitHub
  },
  {
    id: ROLE_IDS.CLIENT_IMPLEMENTOR_IG,
    description: 'Client Implementor Interest Group',
    discord: { role: 'client implementor interest group (synced)' },
    // Discord only
  },
  {
    id: ROLE_IDS.ENTERPRISE_MANAGED_AUTHORIZATION_IG,
    description: 'Enterprise-Managed Authorization Interest Group',
    discord: { role: 'enterprise-managed authorization interest group (synced)' },
    // Discord only
  },
  {
    id: ROLE_IDS.FINANCIAL_SERVICES_IG,
    description: 'Financial Services Interest Group',
    github: { team: 'ig-financial-services', parent: ROLE_IDS.INTEREST_GROUPS },
    discord: { role: 'financial services interest group (synced)' },
  },
  {
    id: ROLE_IDS.GATEWAYS_IG,
    description: 'Gateways Interest Group',
    // No GitHub role yet
    discord: { role: 'gateways interest group (synced)' },
  },
  {
    id: ROLE_IDS.PRIMITIVE_GROUPING_IG,
    description: 'Primitive Grouping Interest Group',
    github: { team: 'primitive-grouping-ig', parent: ROLE_IDS.INTEREST_GROUPS },
    discord: { role: 'primitive grouping interest group (synced)' },
  },
  {
    id: ROLE_IDS.SECURITY_IG,
    description: 'Security Interest Group',
    github: { team: 'security-ig', parent: ROLE_IDS.INTEREST_GROUPS },
    // No synced Discord role yet, see the #security-ig channel
  },
  {
    id: ROLE_IDS.TOOL_ANNOTATIONS_IG,
    description: 'Tool Annotations Interest Group',
    github: { team: 'tool-annotations-ig', parent: ROLE_IDS.INTEREST_GROUPS },
    discord: { role: 'tool annotations interest group (synced)' },
  },

  // ===================
  // WG/IG Facilitators (Discord only)
  // ===================
  {
    id: ROLE_IDS.WG_IG_FACILITATORS,
    description: 'Working Group and Interest Group facilitators with calendar access',
    discord: { role: 'wg/ig facilitators (synced)' },
    // Discord only - grants meet.modelcontextprotocol.io calendar access
    provisionUser: true,
  },

  // ===================
  // Service Accounts (GWS user only, no platform roles)
  // ===================
  {
    id: ROLE_IDS.SERVICE_ACCOUNTS,
    description: 'Service accounts with a Google Workspace user only (no GitHub or Discord)',
    provisionUser: true,
    // No github/discord/google config - exists solely to provision GWS user accounts
  },

  // ===================
  // Email Groups (Google only)
  // ===================
  {
    id: ROLE_IDS.ANTITRUST,
    description: 'Antitrust compliance contacts',
    google: { group: 'antitrust', isEmailGroup: true, allowExternalMembers: true },
    // Google only
  },
  {
    id: ROLE_IDS.APPEALS,
    description: 'Code of Conduct ban appeals inbox',
    google: { group: 'appeals', isEmailGroup: true },
    // Google only
  },
  {
    id: ROLE_IDS.CATCH_ALL,
    description: 'Catch-all email group',
    google: { group: 'catch-all', isEmailGroup: true, allowExternalMembers: true },
    // Google only
  },
] as const;

/**
 * Get a role by ID
 */
export function getRole(id: RoleId): Role | undefined {
  return ROLES.find((r) => r.id === id);
}

/**
 * Get all roles that exist on a specific platform
 */
export function getRolesForPlatform(platform: 'github' | 'discord' | 'google'): Role[] {
  return ROLES.filter((r) => r[platform] !== undefined);
}

/**
 * Build a lookup map of roles by ID
 */
export function buildRoleLookup(): Map<RoleId, Role> {
  return new Map(ROLES.map((r) => [r.id, r]));
}