feat: repo-contributor roles (PR merged in repo X -> role Contributor-X)

- Add repo_contributor_roles config (repo name -> Discord role)
- Planning and apply: grant role when user has merged PR in that repo (all-time)
- Case-insensitive GitHub username and Discord role name matching
- Discord adapter: clearer logs when role not found or add fails
- Bot startup log when repo_contributor_roles enabled; start-bot.sh helper

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: shubham5080

config/example.yaml

@@ -61,6 +61,11 @@ assignments:
 # identity:
 #   unlink_cooldown_hours: 24
 
+# Optional: when a contributor has a PR merged in a repo, grant them the corresponding Discord role
+# (repo name -> Discord role name). Roles are add-only and never auto-removed.
+repo_contributor_roles:
+  castro: "castro"
+
 identity_mappings:
   - github_user: "YOUR_GITHUB_USERNAME"
     discord_user_id: "YOUR_DISCORD_USER_ID"

scripts/debug_repo_contributor_roles.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Debug script: check why repo-contributor role might not be assigned.
+Run from repo root: python scripts/debug_repo_contributor_roles.py --config config/shubh-olrd.yaml
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Ensure src is on path
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SRC = REPO_ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from ghdcbot.config.loader import load_config
+from ghdcbot.plugins.registry import build_adapter
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Debug repo-contributor role assignment")
+    parser.add_argument("--config", required=True, help="Path to config YAML (e.g. config/shubh-olrd.yaml)")
+    args = parser.parse_args()
+    config = load_config(args.config)
+    storage = build_adapter(
+        config.runtime.storage_adapter,
+        data_dir=config.runtime.data_dir,
+    )
+    storage.init_schema()
+
+    repo_contributor_roles = getattr(config, "repo_contributor_roles", None) or {}
+    if not repo_contributor_roles:
+        print("No repo_contributor_roles in config. Add e.g. castro: \"Contributor-castro\"")
+        return
+    print("Config repo_contributor_roles:", repo_contributor_roles)
+    print()
+
+    # 1) Any pr_merged events for the configured repos?
+    from datetime import datetime, timezone
+    from ghdcbot.engine.planning import REPO_CONTRIBUTOR_EPOCH
+    contributions = storage.list_contributions(REPO_CONTRIBUTOR_EPOCH)
+    pr_merged_by_repo: dict[str, list[str]] = {}
+    for e in contributions:
+        if e.event_type == "pr_merged":
+            pr_merged_by_repo.setdefault(e.repo, []).append(e.github_user)
+    for repo in repo_contributor_roles:
+        users = pr_merged_by_repo.get(repo, [])
+        print(f"  Repo '{repo}' (-> role {repo_contributor_roles[repo]}): {len(users)} user(s) with merged PR: {users or 'none'}")
+    if not any(pr_merged_by_repo.get(r) for r in repo_contributor_roles):
+        print("\n  -> No pr_merged events found for configured repos. Ensure:")
+        print("     - You ran run-once or /sync AFTER merging a PR in that repo.")
+        print("     - The merge was within the last 30 days (or cursor covers that time).")
+        print("     - GitHub org in config matches the repo owner (e.g. shubham-orld).")
+    print()
+
+    # 2) Verified identity mappings (used for role assignment)
+    verified = list(storage.list_verified_identity_mappings()) if hasattr(storage, "list_verified_identity_mappings") else []
+    print(f"Verified Discord <-> GitHub links: {len(verified)}")
+    for m in verified:
+        print(f"  Discord {m.discord_user_id} <-> GitHub {m.github_user}")
+    if not verified:
+        print("  -> No verified links. Either:")
+        print("     - Use /link and /verify-link in Discord, OR")
+        print("     - Set identity_mappings in config with real github_user and discord_user_id.")
+    print()
+
+    # 3) Who would get the role? (use same resolution as orchestrator: verified first, then config)
+    from ghdcbot.engine.orchestrator import _resolve_identity_mappings
+    identity_list = _resolve_identity_mappings(storage, getattr(config, "identity_mappings", []) or [])
+    if not identity_list:
+        print("No identity mappings (verified or config). Role cannot be assigned.")
+        return
+    from ghdcbot.engine.planning import repos_with_merged_pr_per_user
+    repos_per_user = repos_with_merged_pr_per_user(storage, identity_list)
+    for mapping in identity_list:
+        gh = mapping.github_user
+        dc = mapping.discord_user_id
+        repos = repos_per_user.get(gh, set())
+        roles_they_get = [repo_contributor_roles[r] for r in repo_contributor_roles if r in repos]
+        print(f"  GitHub {gh} (Discord {dc}): repos with merged PR = {repos}; would get roles = {roles_they_get or 'none'}")
+
+
+if __name__ == "__main__":
+    main()

src/ghdcbot/adapters/discord/api.py

@@ -95,9 +95,15 @@ def add_role(self, discord_user_id: str, role_name: str) -> None:
         """Assign a role to a guild member. Calls Discord API unless request fails."""
         role_id = self._resolve_role_id(role_name)
         if role_id is None:
+            roles, ok = self._list_roles()
+            role_names = [r.get("name") for r in roles if r.get("name")] if ok else []
             self._logger.warning(
-                "Discord role not found; cannot add",
-                extra={"user_id": discord_user_id, "role": role_name},
+                "Discord role not found; cannot add (check name and hierarchy)",
+                extra={
+                    "user_id": discord_user_id,
+                    "role_requested": role_name,
+                    "guild_role_names": role_names[:30],
+                },
             )
             return
         path = f"/guilds/{self._guild_id}/members/{discord_user_id}/roles/{role_id}"
@@ -115,12 +121,17 @@ def add_role(self, discord_user_id: str, role_name: str) -> None:
                 extra={"user_id": discord_user_id, "role": role_name},
             )
         else:
+            try:
+                body = response.text[:500] if response.text else ""
+            except Exception:
+                body = ""
             self._logger.warning(
-                "Discord add role failed",
+                "Discord add role failed (check bot role is above target role and has Manage Roles)",
                 extra={
                     "user_id": discord_user_id,
                     "role": role_name,
                     "status_code": response.status_code,
+                    "response": body,
                 },
             )
 
@@ -233,12 +244,14 @@ def send_dm(self, discord_user_id: str, content: str) -> bool:
             return False
 
     def _resolve_role_id(self, role_name: str) -> str | None:
-        """Resolve role name to Discord role ID. Returns None if not found."""
+        """Resolve role name to Discord role ID (case-insensitive). Returns None if not found."""
         roles, ok = self._list_roles()
         if not ok:
             return None
+        role_name_lower = (role_name or "").strip().lower()
         for role in roles:
-            if role.get("name") == role_name:
+            rname = role.get("name") or ""
+            if rname.strip().lower() == role_name_lower:
                 return role["id"]
         return None
 

src/ghdcbot/bot.py

@@ -61,6 +61,12 @@ def run_bot(config_path: str) -> None:
         config_path,
         config.runtime.data_dir,
     )
+    repo_contributor_roles = getattr(config, "repo_contributor_roles", None) or {}
+    if repo_contributor_roles:
+        logger.info(
+            "repo_contributor_roles enabled: %s (use this same config for /sync to assign these roles)",
+            list(repo_contributor_roles.keys()),
+        )
 
     storage = build_adapter(
         config.runtime.storage_adapter,
@@ -1072,7 +1078,7 @@ async def _on_select_callback(self, interaction: discord.Interaction) -> None:
             await self._on_repo_chosen(interaction, interaction.data["values"][0])
 
         async def _on_repo_chosen(self, interaction: discord.Interaction, repo_value: str) -> None:
-            await interaction.response.defer(ephemeral=False)
+            await interaction.response.defer(ephemeral=True)
             parts = repo_value.split("/", 1)
             if len(parts) != 2:
                 await interaction.followup.send("Invalid repository selection.", ephemeral=True)
@@ -1098,12 +1104,14 @@ async def _on_repo_chosen(self, interaction: discord.Interaction, repo_value: st
             mentor_roles = getattr(self.config, "assignments", None)
             eligible_roles_config = getattr(mentor_roles, "issue_request_eligible_roles", []) if mentor_roles else []
             member_roles_map = self.discord_reader.list_member_roles()
-            channel = interaction.channel
 
-            async def send_repo_list_back(ch: Any) -> None:
+            async def send_repo_list_back(interaction_or_channel: Any) -> None:
                 pending = self.storage.list_pending_issue_requests()
                 if not pending:
-                    await ch.send("No pending issue requests.")
+                    if isinstance(interaction_or_channel, discord.Interaction):
+                        await interaction_or_channel.followup.send("No pending issue requests.", ephemeral=True)
+                    else:
+                        await interaction_or_channel.send("No pending issue requests.")
                     return
                 rl = group_pending_requests_by_repo(pending)
                 now = datetime.now(timezone.utc)
@@ -1112,7 +1120,10 @@ async def send_repo_list_back(ch: Any) -> None:
                     pending, rl, self.storage, self.github_adapter, self.config,
                     self.discord_reader, self.policy,
                 )
-                await ch.send(embed=emb, view=v)
+                if isinstance(interaction_or_channel, discord.Interaction):
+                    await interaction_or_channel.followup.send(embed=emb, view=v, ephemeral=True)
+                else:
+                    await interaction_or_channel.send(embed=emb, view=v)
 
             for req in repo_requests:
                 issue = fetch_issue_context(
@@ -1154,11 +1165,16 @@ async def send_repo_list_back(ch: Any) -> None:
                     discord_sender=self.discord_reader,
                     back_callback=send_repo_list_back,
                 )
-                msg = await channel.send(embed=discord.Embed.from_dict(embed_dict), view=view)
+                # Send as ephemeral followup so only mentor can see it
+                msg = await interaction.followup.send(
+                    embed=discord.Embed.from_dict(embed_dict),
+                    view=view,
+                    ephemeral=True,
+                )
                 view.message = msg
             await interaction.followup.send(
                 f"Showing **{len(repo_requests)}** request(s) for **{repo_value}** above.",
-                ephemeral=False,
+                ephemeral=True,
             )
 
     class IssueRequestReviewView(discord.ui.View):
@@ -1202,8 +1218,8 @@ def __init__(
 
         async def _back_to_repo_list(self, interaction: discord.Interaction) -> None:
             await interaction.response.defer(ephemeral=True)
-            if self.back_callback and interaction.channel:
-                await self.back_callback(interaction.channel)
+            if self.back_callback:
+                await self.back_callback(interaction)
             await interaction.followup.send("Returned to repo list.", ephemeral=True)
 
         def _dm_contributor(self, content: str) -> bool:

src/ghdcbot/config/models.py

@@ -199,6 +199,19 @@ class BotConfig(BaseModel):
     merge_role_rules: MergeRoleRulesConfig | None = None
     # Optional: GitHub snapshot storage
     snapshots: SnapshotConfig | None = None
+    # Optional: repo name -> Discord role for "Contributor-X" (PR merged in repo X grants role)
+    repo_contributor_roles: dict[str, str] | None = None
+
+    @field_validator("repo_contributor_roles")
+    @classmethod
+    def validate_repo_contributor_roles(cls, value: dict[str, str] | None) -> dict[str, str] | None:
+        if value is not None:
+            for repo, role in value.items():
+                if not (repo and repo.strip()):
+                    raise ValueError("repo_contributor_roles: repo names must be non-empty")
+                if not (role and str(role).strip()):
+                    raise ValueError("repo_contributor_roles: discord_role must be non-empty")
+        return value
 
     @field_validator("role_mappings")
     @classmethod

src/ghdcbot/engine/orchestrator.py

@@ -108,6 +108,7 @@ def run_once(self) -> None:
             # Generate audit reports before any mutations are attempted.
             try:
                 merge_role_rules = getattr(self.config, "merge_role_rules", None)
+                repo_contributor_roles = getattr(self.config, "repo_contributor_roles", None)
                 discord_plans = plan_discord_roles(
                     member_roles,
                     scores,
@@ -117,6 +118,7 @@ def run_once(self) -> None:
                     period_start=period_start,
                     period_end=period_end,
                     merge_role_rules=merge_role_rules,
+                    repo_contributor_roles=repo_contributor_roles,
                 )
                 github_plans = _to_github_assignment_plans(issue_plans, review_plans)
                 # Pass difficulty_weights if available (optional parameter, backward compatible)
@@ -187,6 +189,7 @@ def run_once(self) -> None:
 
         apply_github_plans(self.github_writer, issue_plans, review_plans, policy, self.config.github.org)
         merge_role_rules = getattr(self.config, "merge_role_rules", None)
+        repo_contributor_roles = getattr(self.config, "repo_contributor_roles", None)
         apply_discord_roles(
             self.discord_writer,
             member_roles,
@@ -198,6 +201,7 @@ def run_once(self) -> None:
             period_start=period_start,
             period_end=period_end,
             merge_role_rules=merge_role_rules,
+            repo_contributor_roles=repo_contributor_roles,
         )
 
         # Write GitHub snapshots (additive, non-blocking)
@@ -340,13 +344,14 @@ def apply_discord_roles(
     period_start: datetime | None = None,
     period_end: datetime | None = None,
     merge_role_rules: MergeRoleRulesConfig | None = None,
+    repo_contributor_roles: dict[str, str] | None = None,
 ) -> None:
     logger = logging.getLogger("DiscordMutations")
     if not policy.allow_discord_mutations:
         logger.info("Discord mutations disabled", extra={"mode": policy.mode.value})
         return
 
-    from ghdcbot.engine.planning import count_merged_prs_per_user
+    from ghdcbot.engine.planning import count_merged_prs_per_user, repos_with_merged_pr_per_user
 
     score_lookup = {score.github_user: score.points for score in scores}
     role_thresholds = sorted(role_mappings, key=lambda r: r.min_score)
@@ -366,6 +371,11 @@ def apply_discord_roles(
             storage, identity_mappings, period_start, period_end
         )
 
+    # Get repos-with-merged-PR per user if repo-contributor roles are enabled
+    repos_per_user: dict[str, set[str]] = {}
+    if repo_contributor_roles and storage is not None:
+        repos_per_user = repos_with_merged_pr_per_user(storage, identity_mappings)
+
     for mapping in identity_mappings:
         current_roles = set(member_roles.get(mapping.discord_user_id, []))
         points = score_lookup.get(mapping.github_user, 0)
@@ -393,13 +403,32 @@ def apply_discord_roles(
             ]
             # Highest eligible role is the last one (rules sorted by threshold ascending)
             merge_desired = {eligible_merge_roles[-1]} if eligible_merge_roles else set()
+
+        # Repo-contributor desired roles (if enabled)
+        repo_contributor_desired: set[str] = set()
+        if repo_contributor_roles:
+            user_repos = repos_per_user.get(mapping.github_user, set())
+            for repo_name, role_name in repo_contributor_roles.items():
+                if repo_name in user_repos:
+                    repo_contributor_desired.add(role_name)
 
-        # Final desired roles = max(score_based, merge_based)
-        desired_roles = score_desired | merge_desired
+        # Final desired roles = score | merge | repo-contributor
+        desired_roles = score_desired | merge_desired | repo_contributor_desired
 
         # Track newly added roles for congratulatory messages
         newly_added_roles = sorted(desired_roles - current_roles)
-        
+        if newly_added_roles and repo_contributor_desired:
+            for r in newly_added_roles:
+                if r in repo_contributor_desired:
+                    logger.info(
+                        "Repo-contributor role to add",
+                        extra={
+                            "discord_user_id": mapping.discord_user_id,
+                            "github_user": mapping.github_user,
+                            "role": r,
+                        },
+                    )
+                    break
         for role in newly_added_roles:
             discord_writer.add_role(mapping.discord_user_id, role)
             # Send congratulatory message for newly assigned roles
@@ -409,8 +438,8 @@ def apply_discord_roles(
                 role_name=role,
                 policy=policy,
             )
-        # Remove roles that are no longer desired (preserve merge-based roles)
-        roles_to_remove = (current_roles & managed_roles) - (score_desired | merge_desired)
+        # Remove roles only when score-based says so; never remove merge-based or repo-contributor roles
+        roles_to_remove = (current_roles & managed_roles) - desired_roles
         for role in sorted(roles_to_remove):
             discord_writer.remove_role(mapping.discord_user_id, role)