Add /help command and ephemeral locale system

Introduces an interactive Component v2 help browser (/help) with category
navigation, access filtering, and per-command detail pages.

Refactors cog.py → commands.py replacing LazyHybridCommand with
CommandBuilder/GroupBuilder and adding ParamInfo/help text. Adds an
ephemeral locale system (ephemeral_scope, locale_for) so ctx.t() and
send_message() resolve locale automatically. Decouples BaseLayoutView and
BaseModal from Context. Promotes check_user_access to Bot with overloads
for pre-computed args.

Signed-off-by: Taku <45324516+Taaku18@users.noreply.github.com>

Author: Taaku18

config.yaml.example

@@ -70,6 +70,13 @@ bot:
   # Must install the jishaku package with "pdm install -G debug" to enable.
   # enable_jishaku: false
 
+  # Whether to hide owner-only commands from users who are not the bot owner in /help.
+  # hide_owner_commands: true
+
+  # Whether to hide commands the user cannot access from the /help menu.
+  # Cogs with no accessible commands are also omitted.
+  # hide_inaccessible: true
+
 # Required: The URL to the bot's logviewer address.
 log_url: "https://example.com/"
 

modmail/cogs/modmail/__init__.py

@@ -9,7 +9,9 @@
 
 from typing import TYPE_CHECKING
 
-from modmail.core import Bot, Cog, create_cog
+import discord
+
+from modmail.core import Bot, Cog, _, create_cog
 
 from .commands import all_commands
 from .listeners import all_listeners
@@ -20,7 +22,14 @@ class Modmail(Cog):  # Makes linters happy
         """Core Modmail commands cog for the Modmail bot."""
 
 else:
-    Modmail = create_cog("Modmail", all_commands=all_commands, other_methods=all_listeners)
+    Modmail = create_cog(
+        "Modmail",
+        all_commands=all_commands,
+        other_methods=all_listeners,
+        help_name=_("ftl-view-help-category-modmail-name"),
+        help_description=_("ftl-view-help-category-modmail-description"),
+        help_color=discord.Color.blurple(),
+    )
 
 
 __all__ = ["Modmail", "setup"]

modmail/cogs/modmail/commands/__init__.py

@@ -15,13 +15,13 @@
 from .setup import setup_command
 
 if TYPE_CHECKING:
-    from modmail.core import LazyHybridCommand
+    from modmail.core import CommandBuilder
 
 __all__ = [
     "all_commands",
 ]
 
-all_commands: list[LazyHybridCommand[Any]] = [
+all_commands: list[CommandBuilder[Any]] = [
     setup_command,
     reply_command,
     close_command,

modmail/cogs/modmail/commands/close.py

@@ -12,7 +12,7 @@
 
 import discord
 
-from modmail.core import Context, _, in_modmail_ticket, lazy_hybrid_command, staff_only, wrap
+from modmail.core import Context, ParamInfo, _, bot_command, in_modmail_ticket, staff_only
 from modmail.enum import TicketMessageType, TicketStatus
 
 if TYPE_CHECKING:
@@ -24,19 +24,20 @@
 
 
 @staff_only
-@wrap(
-    discord.app_commands.rename,
-    attachment=_("ftl-cmd-close-param-attachment-name"),
-    message=_("ftl-cmd-close-param-message-name"),
-)
-@wrap(
-    discord.app_commands.describe,
-    attachment=_("ftl-cmd-close-param-attachment-description"),
-    message=_("ftl-cmd-close-param-message-description"),
-)
-@lazy_hybrid_command(
+@bot_command(
     name=_("ftl-cmd-close-name"),
     description=_("ftl-cmd-close-description"),
+    help=_("ftl-cmd-close-help"),
+    param_info={
+        "attachment": ParamInfo(
+            name=_("ftl-cmd-close-param-attachment-name"),
+            description=_("ftl-cmd-close-param-attachment-description"),
+        ),
+        "message": ParamInfo(
+            name=_("ftl-cmd-close-param-message-name"),
+            description=_("ftl-cmd-close-param-message-description"),
+        ),
+    },
 )
 @in_modmail_ticket()
 async def close_command(
@@ -46,16 +47,16 @@ async def close_command(
     *,
     message: str = "",
 ) -> None:
-    """Close a ticket in Modmail.
+    """Close the current ticket and send a close message to the recipient(s).
 
     Args:
         cog: The Modmail cog instance.
-        ctx: The command context containing information about the invocation.
-        attachment: An optional attachment to include in the close message. Auto parsed by discord.py.
-        message: The message to send as a close message.
+        ctx: The command context.
+        attachment: Attachment to include in the close message.
+        message: Close message sent to the recipient(s).
 
     Raises:
-        RuntimeError: If an impossible situation is encountered.
+        RuntimeError: When invoked outside a recognized ticket channel.
     """
     if not isinstance(ctx.channel, discord.TextChannel | discord.Thread):
         raise RuntimeError("Command invoked in a non-text channel, which should be impossible.")

modmail/cogs/modmail/commands/reply.py

@@ -11,7 +11,7 @@
 
 import discord
 
-from modmail.core import Context, _, in_modmail_ticket, lazy_hybrid_command, staff_only, wrap
+from modmail.core import Context, ParamInfo, _, bot_command, in_modmail_ticket, staff_only
 
 if TYPE_CHECKING:
     from .. import Modmail
@@ -22,19 +22,20 @@
 
 
 @staff_only
-@wrap(
-    discord.app_commands.rename,
-    attachment=_("ftl-cmd-reply-param-attachment-name"),
-    message=_("ftl-cmd-reply-param-message-name"),
-)
-@wrap(
-    discord.app_commands.describe,
-    attachment=_("ftl-cmd-reply-param-attachment-description"),
-    message=_("ftl-cmd-reply-param-message-description"),
-)
-@lazy_hybrid_command(
+@bot_command(
     name=_("ftl-cmd-reply-name"),
     description=_("ftl-cmd-reply-description"),
+    help=_("ftl-cmd-reply-help"),
+    param_info={
+        "attachment": ParamInfo(
+            name=_("ftl-cmd-reply-param-attachment-name"),
+            description=_("ftl-cmd-reply-param-attachment-description"),
+        ),
+        "message": ParamInfo(
+            name=_("ftl-cmd-reply-param-message-name"),
+            description=_("ftl-cmd-reply-param-message-description"),
+        ),
+    },
 )
 @in_modmail_ticket()
 async def reply_command(
@@ -44,22 +45,18 @@ async def reply_command(
     *,
     message: str = "",
 ) -> None:
-    """Reply to a ticket in Modmail.
-
-    This command allows staff members to reply to a ticket in Modmail. It checks if the
-    command is invoked in the correct channel and sends the message to the ticket.
+    """Send a reply to the ticket's recipient(s).
 
-    The attachment parameter is used to send files along with the message for slash commands.
-    It is automatically parsed by discord.py and injected into ctx.message.
+    At least one of `message` or `attachment` must be provided.
 
     Args:
         cog: The Modmail cog instance.
-        ctx: The command context containing information about the invocation.
-        attachment: An optional attachment to include in the reply. Auto parsed by discord.py.
-        message: The message to send as a reply.
+        ctx: The command context.
+        attachment: File to include in the reply.
+        message: Reply text sent to the recipient(s).
 
     Raises:
-        RuntimeError: If an impossible situation is encountered.
+        RuntimeError: When invoked outside a recognized ticket channel.
     """
     if not isinstance(ctx.channel, discord.TextChannel | discord.Thread):
         raise RuntimeError("Command invoked in a non-text channel, which should be impossible.")

modmail/cogs/modmail/commands/sclose.py

@@ -11,7 +11,7 @@
 
 import discord
 
-from modmail.core import Context, _, in_modmail_ticket, lazy_hybrid_command, staff_only, wrap
+from modmail.core import Context, ParamInfo, _, bot_command, in_modmail_ticket, staff_only
 from modmail.enum import TicketMessageType, TicketStatus
 
 if TYPE_CHECKING:
@@ -23,19 +23,20 @@
 
 
 @staff_only
-@wrap(
-    discord.app_commands.rename,
-    attachment=_("ftl-cmd-sclose-param-attachment-name"),
-    message=_("ftl-cmd-sclose-param-message-name"),
-)
-@wrap(
-    discord.app_commands.describe,
-    attachment=_("ftl-cmd-sclose-param-attachment-description"),
-    message=_("ftl-cmd-sclose-param-message-description"),
-)
-@lazy_hybrid_command(
+@bot_command(
     name=_("ftl-cmd-sclose-name"),
     description=_("ftl-cmd-sclose-description"),
+    help=_("ftl-cmd-sclose-help"),
+    param_info={
+        "attachment": ParamInfo(
+            name=_("ftl-cmd-sclose-param-attachment-name"),
+            description=_("ftl-cmd-sclose-param-attachment-description"),
+        ),
+        "message": ParamInfo(
+            name=_("ftl-cmd-sclose-param-message-name"),
+            description=_("ftl-cmd-sclose-param-message-description"),
+        ),
+    },
 )
 @in_modmail_ticket()
 async def sclose_command(
@@ -45,16 +46,18 @@ async def sclose_command(
     *,
     message: str = "",
 ) -> None:
-    """Silently close a ticket in Modmail.
+    """Close the current ticket without notifying the recipient(s).
+
+    Any `message` or `attachment` is saved in the ticket log but not delivered.
 
     Args:
         cog: The Modmail cog instance.
-        ctx: The command context containing information about the invocation.
-        attachment: An optional attachment to include in the close message. Auto parsed by discord.py.
-        message: The message to save as a close message (not sent to recipient).
+        ctx: The command context.
+        attachment: Attachment to log (not sent to recipients).
+        message: Note saved to the ticket log, not delivered to recipients.
 
     Raises:
-        RuntimeError: If an impossible situation is encountered.
+        RuntimeError: When invoked outside a recognized ticket channel.
     """
     if not isinstance(ctx.channel, discord.TextChannel | discord.Thread):
         raise RuntimeError("Command invoked in a non-text channel, which should be impossible.")