Flatten modmail/core/internals/ into modmail/core/, add PermissionCommandIndex with locale-aware command resolution

Author: Taaku18

CLAUDE.md

@@ -4,7 +4,7 @@ Modmail is a Discord DM-based support ticket bot. It routes user DMs into staff
 
 ## Structure
 
-- Core runtime and Discord integration live in `modmail/core/` (bot, permissions, translator, internal helpers).
+- Core runtime and Discord integration live in `modmail/core/` — flat layout, one concern per file: bot, cog base/lazy-command machinery, context helpers, argument converters, embed builder, access-level decorators and command permission index, staff guild lifecycle, FTL translator, and a private ticket view.
 - Persistence is abstracted behind `modmail/backends/common/` (`DBBackend`, `DBClient`, shared models) with concrete implementations in `modmail/backends/mongodb/` and `modmail/backends/sql/`.
 - Configuration models and loading logic live in `modmail/config/`.
 - Discord-facing behavior is in `modmail/cogs/modmail/` (modmail flows) and `modmail/cogs/utility/` (utility commands).

config.yaml.example

@@ -139,11 +139,8 @@ permission:
   #   * manager
   #   * admin
   #   * owner
-  # Command names should be as appears in the code.
-  # For example, the `/status clear` command is called "status_clear_command" in the code (cogs/utility/commands/status.py).
-  # So you would use "status clear" as the command name for the override.
-  # For most cases, the command name is the same as the actual command.
-  # You can set wildcard (+) to override a command group. For example, "status+" will override all related commands (i.e. `/status clear`).
+  # The command name is the English name of the command as it appears in Discord (e.g. "status clear" for `/status clear`),
+  # You can append "+" to a group name to override all of its subcommands (e.g. "status+" covers `/status clear`).
   overrides:
     some command name: staff
     some group+: everyone

modmail/__init__.py

@@ -12,19 +12,29 @@
 import sys
 from importlib.metadata import version
 from textwrap import dedent
-from typing import NoReturn
+from typing import TYPE_CHECKING, NoReturn
 
-from .config import Config, load_config
+if TYPE_CHECKING:
+    from .config import Config
 
-__all__ = ["__version__", "init", "run_bot"]
+    CONFIG: Config
+
+__all__ = ["CONFIG", "__version__", "init", "run_bot"]
 
 __version__ = version("modmail.py")
 
 logger = _logging.getLogger(__name__)
 
+_state: dict[str, Config] = {}
+
 
-# Global variable to store the loaded configuration.
-CONFIG: Config
+def __getattr__(name: str) -> object:
+    if name == "CONFIG":
+        try:
+            return _state["config"]
+        except KeyError:
+            raise RuntimeError("modmail.CONFIG is not available — call modmail.init() first") from None
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 def init(config_file_path: str = "config.yaml", *, configure_logging: bool = True) -> None:
@@ -34,20 +44,20 @@ def init(config_file_path: str = "config.yaml", *, configure_logging: bool = Tru
         config_file_path: Path to the configuration file. Defaults to "config.yaml".
         configure_logging: Whether to configure logging when logging is enabled in the configs.
     """
-    global CONFIG  # noqa: PLW0603
-    # noinspection PyPep8Naming
-    CONFIG_ = load_config(config_file_path)  # noqa: N806
-    if CONFIG_ is None:
+    from .config import load_config
+
+    config = load_config(config_file_path)
+    if config is None:
         logger.critical("Failed to load config. Exiting.")
         sys.exit(1)
-    CONFIG = CONFIG_  # pyright: ignore [reportConstantRedefinition]
+    _state["config"] = config
 
-    if configure_logging and CONFIG.logging.enabled:
+    if configure_logging and config.logging.enabled:
         from .logging import setup_logging
 
         setup_logging()
 
-    logger.debug("Loaded config: %s", CONFIG.model_dump_json())
+    logger.debug("Loaded config: %s", config.model_dump_json(indent=2))
 
 
 def run_bot() -> NoReturn:
@@ -59,7 +69,7 @@ def run_bot() -> NoReturn:
 
     This function does not return as it runs the bot until termination.
     """
-    if "CONFIG" not in globals():
+    if "config" not in _state:
         logger.warning("init() was not called. Calling init() with the default args.")
         init()
 
@@ -75,9 +85,10 @@ def run_bot() -> NoReturn:
     )
     current_time_text = datetime.datetime.now(tz=datetime.UTC).astimezone().strftime("%B %d, %Y %H:%M:%S %Z")
     python_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
-    allowed_locale = CONFIG.allowed_locales
+    config = _state["config"]
+    allowed_locale = config.allowed_locales
     enabled_locales = ", ".join(
-        [CONFIG.default_locale] + [locale for locale in allowed_locale if locale != CONFIG.default_locale]
+        [config.default_locale] + [locale for locale in allowed_locale if locale != config.default_locale]
     )
 
     modmail_text_lines: list[str] = []
@@ -88,7 +99,7 @@ def run_bot() -> NoReturn:
     modmail_text_lines += [
         (
             f"Version: {__version__} | Python: {python_version} | "
-            f"Language{'s' if len(CONFIG.allowed_locales) != 1 else ''}: {enabled_locales}"
+            f"Language{'s' if len(config.allowed_locales) != 1 else ''}: {enabled_locales}"
         )
     ]
     modmail_text_lines += [""]

modmail/cogs/modmail/commands/setup.py

@@ -565,7 +565,7 @@ async def do_setup(ctx: Context) -> None:
         logger.debug("Bot does not have enough permissions to run setup in %s", ctx.guild)
         return
 
-    wizard = SetupWizardView(ctx=ctx, show_reconfigure_warning=ctx.bot.staff_guild.is_configured())
+    wizard = SetupWizardView(ctx=ctx, show_reconfigure_warning=ctx.bot.staff_guild.is_setup())
     await wizard.build()
 
     wizard.message = await ctx.reply(view=wizard)

modmail/cogs/modmail/listeners/dm_receive.py

@@ -47,7 +47,7 @@ async def dm_receive(cog: Modmail, message: discord.Message) -> None:
     success_emoji = "✅"
     error_emoji = "❌"
 
-    if not staff_guild.is_configured():
+    if not staff_guild.is_setup():
         prefix = await cog.bot.get_prefix(message)
         if isinstance(prefix, str):
             prefix = [prefix]

modmail/cogs/utility/commands/profile.py

@@ -173,50 +173,67 @@ async def on_submit(self, interaction: discord.Interaction) -> None:
         Args:
             interaction: The submission interaction from Discord.
         """
-        command_name = utils.sanitize_user_command_name(self.command_name.value)
-        command_name_no_wildcard = command_name.split("+")[0].strip()
+        locale = str(interaction.locale) if interaction.locale else CONFIG.default_locale
+        index = self._ctx.bot.permission_command_index(locale)
+
+        canonical = index.resolve(self.command_name.value)
+        if canonical is None:
+            await interaction.response.send_message(
+                self._ctx.translate(
+                    _(
+                        "ftl-cmd-profile-override-command-not-found",
+                        command=self.command_name.value,
+                    )
+                ),
+                ephemeral=True,
+            )
+            return
+
+        base = canonical.removesuffix("+")
 
         for bot_command in self._ctx.bot.walk_commands():
-            bot_command_name = utils.get_command_name(bot_command)
-            if bot_command_name == command_name_no_wildcard:
-                if "+" in command_name and not isinstance(bot_command, commands.Group):
-                    command_name = command_name_no_wildcard
+            if self._ctx.bot.get_canonical_command_name(bot_command) == base:
+                if canonical != base and not isinstance(bot_command, commands.Group):
+                    canonical = base  # wildcards only apply to groups
+
                 if self._ctx.bot.get_command_access_level(bot_command) == RequiredAccessLevel.owner:
+                    # Only actual owner allowed to override owner-only commands
                     if not await self._ctx.bot.is_owner(self._ctx.author):
                         await interaction.response.send_message(
-                            self._ctx.translate(_("ftl-cmd-profile-override-owner-command", command=command_name)),
+                            self._ctx.translate(
+                                _(
+                                    "ftl-cmd-profile-override-owner-command",
+                                    command=self.command_name.value,
+                                )
+                            ),
                             ephemeral=True,
                         )
                         return
                 break
-        else:
-            await interaction.response.send_message(
-                self._ctx.translate(_("ftl-cmd-profile-override-command-not-found", command=command_name)),
-                ephemeral=True,
-            )
-            return
+
+        display = index.label(canonical)
 
         changed = self._editor_view.resync_profile()
-        if self.profile.permission_overrides.get(command_name) == self._override_value:
+        if self.profile.permission_overrides.get(canonical) == self._override_value:
             if changed:
                 await self._editor_view.rebuild()
             await interaction.response.send_message(
                 self._ctx.translate(
-                    _("ftl-modal-profile-add-override-already-allow", command=command_name)
+                    _("ftl-modal-profile-add-override-already-allow", command=display)
                     if self._override_value == PermissionOverrideValue.allow
-                    else _("ftl-modal-profile-add-override-already-deny", command=command_name)
+                    else _("ftl-modal-profile-add-override-already-deny", command=display)
                 ),
                 ephemeral=True,
             )
             return
 
         overrides = self.profile.permission_overrides.copy()
-        overrides[command_name] = self._override_value
+        overrides[canonical] = self._override_value
         new_profile = self.profile.model_copy(update={"permission_overrides": overrides})
         try:
             await self._ctx.bot.database_client.update_profile(new_profile)
         except DatabaseOperationError as e:
-            logger.error("Failed to set override %r on profile %d: %s", command_name, new_profile.profile_id, e)
+            logger.error("Failed to set override %r on profile %d: %s", canonical, new_profile.profile_id, e)
             if changed:
                 await self._editor_view.rebuild()
             await interaction.response.send_message(
@@ -227,17 +244,17 @@ async def on_submit(self, interaction: discord.Interaction) -> None:
         logger.debug(
             "Set %s override for command %r on profile %d.",
             self._override_value.value,
-            command_name,
+            canonical,
             new_profile.profile_id,
         )
         self._editor_view.profile = new_profile
         await self._editor_view.rebuild()
 
         await interaction.response.send_message(
             self._ctx.translate(
-                _("ftl-view-profile-editor-override-allow-success", command=command_name)
+                _("ftl-view-profile-editor-override-allow-success", command=display)
                 if self._override_value == PermissionOverrideValue.allow
-                else _("ftl-view-profile-editor-override-deny-success", command=command_name)
+                else _("ftl-view-profile-editor-override-deny-success", command=display)
             ),
             ephemeral=True,
         )
@@ -280,26 +297,43 @@ async def on_submit(self, interaction: discord.Interaction) -> None:
         Args:
             interaction: The submission interaction from Discord.
         """
-        name = utils.sanitize_user_command_name(self.override_name.value)
+        locale = str(interaction.locale) if interaction.locale else CONFIG.default_locale
+        index = self._ctx.bot.permission_command_index(locale)
+        sanitized = index.sanitize(self.override_name.value)
+
+        resolved = index.resolve(self.override_name.value, allow_raw_key=True)
 
         changed = self._editor_view.resync_profile()
-        if name not in self.profile.permission_overrides:
+
+        # Remove resolved if exists, otherwise remove sanitized input if it's an orphaned key
+        key_to_remove = (
+            resolved
+            if resolved is not None and resolved in self.profile.permission_overrides
+            else sanitized
+            if sanitized in self.profile.permission_overrides
+            else None
+        )
+
+        if key_to_remove is None:
             if changed:
                 await self._editor_view.rebuild()
             await interaction.response.send_message(
-                self._ctx.translate(_("ftl-modal-profile-remove-override-not-found", command=name)),
+                self._ctx.translate(
+                    _("ftl-modal-profile-remove-override-not-found", command=self.override_name.value)
+                ),
                 ephemeral=True,
             )
             return
 
-        if not await self._editor_view.remove_override(name, interaction):
+        if not await self._editor_view.remove_override(key_to_remove, interaction):
             if changed:
                 await self._editor_view.rebuild()
             return
 
         await self._editor_view.rebuild()
+        display = index.label(key_to_remove)
         await interaction.response.send_message(
-            self._ctx.translate(_("ftl-modal-profile-remove-override-success", command=name)),
+            self._ctx.translate(_("ftl-modal-profile-remove-override-success", command=display)),
             ephemeral=True,
         )
 
@@ -383,7 +417,7 @@ async def _on_confirm(self, interaction: discord.Interaction) -> None:
         access_sync_failed = False
         if self.profile.access_level is not None and self.profile.access_level != AccessLevel.everyone:
             try:
-                await self._ctx.bot.staff_guild.revoke_access(self.profile.profile_id, self.profile.profile_type)
+                await self._ctx.bot.staff_guild.revoke_access(self.profile.profile_id)
             except Exception as e:
                 logger.error("Failed to revoke Discord access for profile %d: %s", self.profile.profile_id, e)
                 access_sync_failed = True
@@ -732,9 +766,7 @@ async def on_level_select(interaction: discord.Interaction) -> None:
             access_sync_failed = False
             try:
                 if previously_had_access and not now_has_access:
-                    await self._ctx.bot.staff_guild.revoke_access(
-                        self.profile.profile_id, self.profile.profile_type
-                    )
+                    await self._ctx.bot.staff_guild.revoke_access(self.profile.profile_id)
                 elif not previously_had_access and now_has_access:
                     await self._ctx.bot.staff_guild.grant_access(
                         self.profile.profile_id, self.profile.profile_type
@@ -793,6 +825,14 @@ def _build_overrides_section(self) -> list[discord.ui.Item[ProfileEditorView]]:
         Returns:
             A list of Component v2 items for the overrides section of the editor card.
         """
+        locale = str(self._ctx.interaction.locale) if self._ctx.interaction else CONFIG.default_locale
+        index = self._ctx.bot.permission_command_index(locale)
+
+        def _label(k: str) -> str:
+            if k.removesuffix("+") not in index.keys:
+                return "⚠️ " + k
+            return index.label(k)
+
         # ── Header: override count ──
 
         overrides_header = self._ctx.translate(
@@ -830,9 +870,9 @@ async def on_add_deny(interaction: discord.Interaction) -> None:
         if self.profile.permission_overrides:
             lines = [
                 self._ctx.translate(
-                    _("ftl-view-profile-editor-override-line-allow", command=k)
+                    _("ftl-view-profile-editor-override-line-allow", command=_label(k))
                     if v == PermissionOverrideValue.allow
-                    else _("ftl-view-profile-editor-override-line-deny", command=k)
+                    else _("ftl-view-profile-editor-override-line-deny", command=_label(k))
                 )
                 for k, v in self.profile.permission_overrides.items()
             ]
@@ -843,7 +883,7 @@ async def on_add_deny(interaction: discord.Interaction) -> None:
 
                 remove_options = [
                     discord.SelectOption(
-                        label=k,
+                        label=_label(k)[:100],
                         value=k,
                         description=self._ctx.translate(
                             _("ftl-view-profile-editor-override-value-allow")
@@ -1054,7 +1094,7 @@ async def profile_delete_command(
     access_sync_failed = False
     if profile.access_level is not None and profile.access_level != AccessLevel.everyone:
         try:
-            await ctx.bot.staff_guild.revoke_access(profile.profile_id, profile.profile_type)
+            await ctx.bot.staff_guild.revoke_access(profile.profile_id)
         except Exception as e:
             logger.error("Failed to revoke Discord access for profile %d: %s", profile.profile_id, e)
             access_sync_failed = True

modmail/config/models/permission_model.py

@@ -10,7 +10,6 @@
 
 from pydantic import BaseModel, Field, field_validator
 
-from modmail import utils
 from modmail.enum import RequiredAccessLevel
 
 __all__ = ["PermissionConfig"]
@@ -57,7 +56,7 @@ def sanitize_overrides_values_config(
 
         new_v: dict[str, RequiredAccessLevel] = {}
         for key, value in v.items():
-            key = utils.sanitize_user_command_name(key)
+            key = key.casefold().strip()
             if isinstance(value, str):
                 try:
                     new_v[key] = RequiredAccessLevel[value.casefold()]

modmail/core/__init__.py

@@ -9,12 +9,16 @@
 
 try:  # Check if modmail is initialized
     from .. import CONFIG
-
-    del CONFIG
-except ImportError as e:  # pragma: no cover
+except RuntimeError as e:  # pragma: no cover
     raise RuntimeError("Did you forget to first run modmail.init()?") from e
+else:
+    del CONFIG
 
 from .bot import *
-from .internals import *
+from .cog import *
+from .context import *
+from .converters import *
+from .embed import *
 from .permission import *
+from .staff_guild import *
 from .translator import *