config.sample.py

@@ -7,8 +7,6 @@ CONFIG = {
 
 	# Client token obtained from the Discord application dashboard. See setup documentation.
 	'client_token': '<REQUIRED>',
-    # Bot commands will be invoked by posting a message with this prefix.
-	'command_prefix': '$rb_',
     # Path to a directory where guild-specific preferences will be stored.
     # Each guild's settings will be saved as a JSON file. Path should end with a slash.
 	'config_path': 'config/',
@@ -46,6 +44,8 @@ CONFIG = {
 	'info_emoji': 'ℹ️',
 	# Logging something that happened on the server (e.g. a user joined the server)
 	'log_emoji': '📋',
+	# A task is in progress
+	'wait_emoji': '⏳',
 
     # -----------------------------------------------------------------------
     # Default values for cog-specific settings that a guild has not overridden

rocketbot/bot.py

@@ -5,22 +5,27 @@ from discord import Intents
 from discord.ext import commands
 
 from config import CONFIG
-from rocketbot.utils import bot_log
+from rocketbot.cogsetting import CogSetting
+from rocketbot.utils import bot_log, dump_stacktrace
+
 
 class Rocketbot(commands.Bot):
 	"""
 	Bot subclass
 	"""
-	def __init__(self, command_prefix, **kwargs):
-		super().__init__(command_prefix, **kwargs)
+	def __init__(self, **kwargs):
+		# Bot requires command_prefix, even though we're only using slash commands,
+		# not commands in message content. Giving an unlikely prefix of private-use
+		# Unicode characters. This isn't a security thing, just avoiding showing a
+		# "command not found" error if someone happens to start a message with
+		# something more common.
+		super().__init__(command_prefix='\uED1E\uEA75\uF00D', **kwargs)
+		self.__commands_set_up = False
+		self.__first_ready = True
 
 	async def on_command_error(self, context: commands.Context, exception: BaseException) -> None:
 		bot_log(None, None, f'Command error')
-		ex = exception
-		while ex is not None:
-			print(f'Caused by {ex}')
-			traceback.print_exception(type(ex), ex, ex.__traceback__)
-			ex = ex.__cause__ if ex.__cause__ != ex else None
+		dump_stacktrace(exception)
 		if context.guild is None or \
 				context.message.channel is None or \
 				context.message.author.bot:
@@ -43,6 +48,32 @@ class Rocketbot(commands.Bot):
 			f'	event kwargs: {kwargs}' + \
 			traceback.format_exc())
 
+	async def on_ready(self):
+		if self.__first_ready:
+			self.__first_ready = False
+			if not self.__commands_set_up:
+				await self.__set_up_commands()
+			bot_log(None, None, 'Bot done initializing')
+			bot_log(None, None, f"Type /help in Discord for available commands.")
+			print('----------------------------------------------------------')
+
+	async def __set_up_commands(self):
+		if self.__commands_set_up:
+			return
+		self.__commands_set_up = True
+		for cog in self.cogs.values():
+			from rocketbot.cogs.basecog import BaseCog
+			if isinstance(cog, BaseCog):
+				bcog: BaseCog = cog
+				if len(bcog.settings) > 0:
+					CogSetting.set_up_all(bcog, self, bcog.settings)
+		try:
+			synced_commands = await self.tree.sync()
+			for command in synced_commands:
+				bot_log(None, None, f'Synced command: /{command.name}')
+		except Exception as e:
+			dump_stacktrace(e)
+
 # Current active bot instance
 rocketbot: Optional[Rocketbot] = None
 
@@ -52,18 +83,19 @@ def __create_bot():
 		return
 	bot_log(None, None, 'Creating bot...')
 	intents = Intents.default()
-	intents.messages = True  # pylint: disable=assigning-non-slot
-	intents.message_content = True  # pylint: disable=assigning-non-slot
-	intents.members = True  # pylint: disable=assigning-non-slot
+	intents.messages = True
+	intents.message_content = True
+	intents.members = True
 	intents.presences = True
-	rocketbot = Rocketbot(command_prefix=CONFIG['command_prefix'], intents=intents)
+	rocketbot = Rocketbot(intents=intents)
 __create_bot()
 
 from rocketbot.cogs.autokickcog import AutoKickCog
 from rocketbot.cogs.configcog import ConfigCog
 from rocketbot.cogs.crosspostcog import CrossPostCog
+from rocketbot.cogs.gamescog import GamesCog
 from rocketbot.cogs.generalcog import GeneralCog
-from rocketbot.cogs.joinagecog import JoinAgeCog
+from rocketbot.cogs.helpcog import HelpCog
 from rocketbot.cogs.joinraidcog import JoinRaidCog
 from rocketbot.cogs.logcog import LoggingCog
 from rocketbot.cogs.patterncog import PatternCog
@@ -72,7 +104,6 @@ from rocketbot.cogs.usernamecog import UsernamePatternCog
 
 async def start_bot():
 	bot_log(None, None, 'Bot initializing...')
-	bot_log(None, None, f"Type {CONFIG['command_prefix']}help in Discord for available commands.")
 
 	# Core
 	await rocketbot.add_cog(GeneralCog(rocketbot))
@@ -81,7 +112,8 @@ async def start_bot():
 	# Optional
 	await rocketbot.add_cog(AutoKickCog(rocketbot))
 	await rocketbot.add_cog(CrossPostCog(rocketbot))
-	await rocketbot.add_cog(JoinAgeCog(rocketbot))
+	await rocketbot.add_cog(GamesCog(rocketbot))
+	await rocketbot.add_cog(HelpCog(rocketbot))
 	await rocketbot.add_cog(JoinRaidCog(rocketbot))
 	await rocketbot.add_cog(LoggingCog(rocketbot))
 	await rocketbot.add_cog(PatternCog(rocketbot))

rocketbot/cogs/autokickcog.py

@@ -1,7 +1,8 @@
 from datetime import datetime, timedelta
 
 from discord import Guild, Member, Status
-from discord.ext import commands, tasks
+from discord.ext import tasks
+from discord.ext.commands import Cog
 from discord.ext.tasks import Loop
 
 from config import CONFIG
@@ -32,28 +33,42 @@ class AutoKickCog(BaseCog, name='Auto Kick'):
 	"""
 	Cog for automatically kicking ALL new joins. For temporary use during join raids.
 	"""
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='autokick',
-		description='Whether this cog is enabled for a guild.')
-	SETTING_BAN_COUNT = CogSetting('bancount', int,
+		description='Whether this module is enabled for a guild.',
+	)
+	SETTING_BAN_COUNT = CogSetting(
+		'bancount',
+		int,
+		default_value=0,
 		brief='number of repeat kicks before a ban',
-			description='The number of times a user can join and be kicked ' + \
-					'before the next rejoin will result in a ban. A value of 0 ' + \
+		description='The number of times a user can join and be kicked '
+					'before the next rejoin will result in a ban. A value of 0 '
 					'disables this feature (only kick, never ban).',
-			usage='<count:int>',
-			min_value=0)
-	SETTING_OFFLINE_ONLY = CogSetting('offlineonly', bool,
+		min_value=0,
+	)
+	SETTING_OFFLINE_ONLY = CogSetting(
+		'offlineonly',
+		bool,
+		default_value=False,
 		brief='whether to only kick users whose status is offline',
-			description='Compromised accounts may have a status of offline. ' + \
-					'If this setting is enabled, the user\'s status will be ' + \
-					'checked a few seconds after joining. If it is offline ' + \
+		description='Compromised accounts may have a status of offline. '
+					'If this setting is enabled, the user\'s status will be '
+					'checked a few seconds after joining. If it is offline '
 					'they will be kicked.',
-			usage='<true|false>')
+	)
 
 	STATE_KEY_RECENT_KICKS = "AutoKickCog.recent_joins"
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='autokick',
+			short_description='Automatically kicks all new users as soon as they join.',
+		)
 		self.add_setting(AutoKickCog.SETTING_ENABLED)
 		self.add_setting(AutoKickCog.SETTING_BAN_COUNT)
 		self.add_setting(AutoKickCog.SETTING_OFFLINE_ONLY)
@@ -61,17 +76,7 @@ class AutoKickCog(BaseCog, name='Auto Kick'):
 		timer: Loop = self.status_check_timer
 		timer.start()
 
-	@commands.group(
-		brief='Automatically kicks all new users as soon as they join',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def autokick(self, context: commands.Context):
-		"""Auto-kick"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_join(self, member: Member) -> None:
 		"""Event handler"""
 		guild: Guild = member.guild
@@ -118,9 +123,8 @@ class AutoKickCog(BaseCog, name='Auto Kick'):
 		else:
 			context.record_kick(datetime.now())
 		max_kick_count: int = self.get_guild_setting(guild, self.SETTING_BAN_COUNT)
-		disable_help = f'To disable this feature: `{CONFIG["command_prefix"]}autokick disable`.'
-		ban_help = f'To configure ban threshold: `{CONFIG["command_prefix"]}autokick ' + \
-			'setbancount #` (0 to disable).'
+		disable_help = f'To disable this feature: `/disable autokick`.'
+		ban_help = f'To configure ban threshold: `/set autokick_bancount #` (0 to disable)'
 		if max_kick_count > 0 and context.kick_count > max_kick_count:
 			await member.ban(reason=f'Rocketbot: Ban after {context.kick_count} joins',
 				delete_message_days=0)

rocketbot/cogs/basecog.py

@@ -4,9 +4,12 @@ Base cog class and helper classes.
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from discord import Guild, Member, Message, RawReactionActionEvent, TextChannel
+import discord
+from discord import Guild, Interaction, Member, Message, RawReactionActionEvent, TextChannel
 from discord.abc import GuildChannel
-from discord.ext import commands
+from discord.app_commands import AppCommandError
+from discord.app_commands.errors import CommandInvokeError
+from discord.ext.commands import Cog
 
 from config import CONFIG
 from rocketbot.bot import Rocketbot
@@ -14,24 +17,79 @@ from rocketbot.botmessage import BotMessage, BotMessageReaction
 from rocketbot.cogsetting import CogSetting
 from rocketbot.collections import AgeBoundDict
 from rocketbot.storage import Storage
-from rocketbot.utils import bot_log
+from rocketbot.utils import bot_log, dump_stacktrace
 
 class WarningContext:
 	def __init__(self, member: Member, warn_time: datetime):
 		self.member = member
 		self.last_warned = warn_time
 
-class BaseCog(commands.Cog):
+class BaseCog(Cog):
 	STATE_KEY_RECENT_WARNINGS = "BaseCog.recent_warnings"
 
 	"""
 	Superclass for all Rocketbot cogs. Provides lots of conveniences for
 	common tasks.
 	"""
-	def __init__(self, bot):
+	def __init__(
+			self,
+			bot: Rocketbot,
+			config_prefix: Optional[str],
+			short_description: str,
+			long_description: Optional[str] = None,
+	):
+		"""
+		Parameters
+		----------
+		bot: Rocketbot
+		config_prefix: str
+		    Prefix to show on variables in /set and /get commands to namespace
+		    configuration variables. E.g. if config_prefix is "foo", a config
+		    variable named "bar" in that cog will show as "foo.bar". If None,
+		    config variable acts as a top-level variable with no prefix.
+		"""
 		self.bot: Rocketbot = bot
-		self.are_settings_setup = False
-		self.settings = []
+		self.are_settings_setup: bool = False
+		self.settings: list[CogSetting] = []
+		self.config_prefix: Optional[str] = config_prefix
+		self.short_description: str = short_description
+		self.long_description: str = long_description
+
+	async def cog_app_command_error(self, interaction: Interaction, error: AppCommandError) -> None:
+		if isinstance(error, CommandInvokeError):
+			error = error.original
+		dump_stacktrace(error)
+		message = f"\nException: {error.__class__.__name__}, "\
+				  f"Command: {interaction.command.qualified_name if interaction.command else None}, "\
+				  f"User: {interaction.user}, "\
+				  f"Time: {discord.utils.format_dt(interaction.created_at, style='F')}"
+		try:
+			await interaction.response.send_message(f"An error occurred: {message}", ephemeral=True)
+		except discord.InteractionResponded:
+			await interaction.followup.send(f"An error occurred: {message}", ephemeral=True)
+
+	@property
+	def basecogs(self) -> list['BaseCog']:
+		"""
+		List of BaseCog instances. Cogs that do not inherit from BaseCog are omitted.
+		"""
+		return [
+			bcog
+			for bcog in sorted(self.bot.cogs.values(), key=lambda c: c.qualified_name)
+			if isinstance(bcog, BaseCog)
+		]
+
+	@property
+	def basecog_map(self) -> dict[str, 'BaseCog']:
+		"""
+		Map of qualified names to BaseCog instances. Cogs that do not inherit
+		from BaseCog are omitted.
+		"""
+		return {
+			qname: bcog
+			for qname, bcog in self.bot.cogs.items()
+			if isinstance(bcog, BaseCog)
+		}
 
 	# Config
 
@@ -65,7 +123,7 @@ class BaseCog(commands.Cog):
 
 	@classmethod
 	def get_guild_setting(cls,
-			guild: Guild,
+			guild: Optional[Guild],
 			setting: CogSetting,
 			use_cog_default_if_not_set: bool = True):
 		"""
@@ -74,11 +132,17 @@ class BaseCog(commands.Cog):
 		unless the optional `use_cog_default_if_not_set` is `False`, then
 		`None` will be returned.
 		"""
+		if guild:
 			key = f'{cls.__name__}.{setting.name}'
 			value = Storage.get_config_value(guild, key)
-		if value is None and use_cog_default_if_not_set:
-			value = cls.get_cog_default(setting.name)
+			if value is not None:
 				return value
+		if use_cog_default_if_not_set:
+			config_default = cls.get_cog_default(setting.name)
+			if config_default is not None:
+				return None
+			return setting.default_value
+		return None
 
 	@classmethod
 	def set_guild_setting(cls,
@@ -96,8 +160,8 @@ class BaseCog(commands.Cog):
 		key = f'{cls.__name__}.{setting.name}'
 		Storage.set_config_value(guild, key, new_value)
 
-	@commands.Cog.listener()
-	async def on_ready(self):
+	# @commands.Cog.listener()
+	async def __on_ready(self):
 		"""Event listener"""
 		if not self.are_settings_setup:
 			self.are_settings_setup = True
@@ -138,7 +202,7 @@ class BaseCog(commands.Cog):
 			BaseCog.STATE_KEY_RECENT_WARNINGS)
 		if recent_warns is None:
 			recent_warns = AgeBoundDict(timedelta(seconds=CONFIG['squelch_warning_seconds']),
-				lambda i, context : context.last_warned)
+				lambda i, context0 : context0.last_warned)
 			Storage.set_state_value(member.guild, BaseCog.STATE_KEY_RECENT_WARNINGS, recent_warns)
 		context: WarningContext = recent_warns.get(member.id)
 		if context is None:
@@ -177,7 +241,7 @@ class BaseCog(commands.Cog):
 		await message.update()
 		return message.is_sent()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_raw_reaction_add(self, payload: RawReactionActionEvent):
 		"""Event handler"""
 		# Avoid any unnecessary requests. Gets called for every reaction

rocketbot/cogs/configcog.py

@@ -1,101 +1,126 @@
 """
 Cog handling general configuration for a guild.
 """
-from discord import Guild, TextChannel
-from discord.ext import commands
+from typing import Union, Optional
+
+from discord import Guild, Permissions, TextChannel, Interaction, Role, User
+from discord.app_commands import Group
+from discord.ext.commands import Bot
 
 from config import CONFIG
 from rocketbot.storage import ConfigKey, Storage
 from rocketbot.cogs.basecog import BaseCog
+from rocketbot.utils import MOD_PERMISSIONS
+
 
 class ConfigCog(BaseCog, name='Configuration'):
 	"""
 	Cog for handling general bot configuration.
 	"""
-	@commands.group(
-		brief='Manages general bot configuration'
+
+	def __init__(self, bot: Bot) -> None:
+		super().__init__(
+			bot,
+			config_prefix='config',
+			short_description='Manages general bot configuration.',
+		)
+
+	config = Group(
+		name='config',
+		description='Manages general bot configuration.',
+		guild_only=True,
+		default_permissions=MOD_PERMISSIONS,
 	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def config(self, context: commands.Context):
-		"""General guild configuration command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
 
 	@config.command(
-		brief='Sets the mod warning channel',
-		description='Run this command in the channel where bot messages ' +
-			'intended for server moderators should be sent. Other bot ' +
-			'messages may still be posted in the channel a command was ' +
-			'invoked in. If no output channel is set, mod-related messages ' +
-			'will not be posted!',
+		description='Sets mod warnings to post in the current channel.',
+		extras={
+			'long_description': 'Run this command in the channel where bot messages intended '
+								'for server moderators should be sent. Other bot messages may '
+								'still be posted in the channel a command was invoked in. **If '
+								'no output channel is set, mod-related messages will not be posted!**',
+		},
 	)
-	async def setwarningchannel(self, context: commands.Context) -> None:
-		"""Command handler"""
-		guild: Guild = context.guild
-		channel: TextChannel = context.channel
+	async def set_warning_channel(self, interaction: Interaction) -> None:
+		"""
+		Sets mod warnings to post in the current channel.
+
+		Run this command in the channel where bot messages intended for server
+		moderators should be sent. Other bot messages may still be posted in
+		the channel a command was invoked in. If no output channel is set,
+		mod-related messages will not be posted!
+		"""
+		guild: Guild = interaction.guild
+		channel: TextChannel = interaction.channel
 		Storage.set_config_value(guild, ConfigKey.WARNING_CHANNEL_ID,
-			context.channel.id)
-		await context.message.reply(
+			interaction.channel.id)
+		await interaction.response.send_message(
 			f'{CONFIG["success_emoji"]} Warning channel updated to {channel.mention}.',
-			mention_author=False)
+			ephemeral=True,
+		)
 
 	@config.command(
-		brief='Shows the mod warning channel',
-		description='Shows the configured channel (if any) where mod ' + \
-			'warnings will be posted.',
+		description='Shows the configured mod warning channel, if any.'
 	)
-	async def getwarningchannel(self, context: commands.Context) -> None:
-		"""Command handler"""
-		guild: Guild = context.guild
+	async def get_warning_channel(self, interaction: Interaction) -> None:
+		guild: Guild = interaction.guild
 		channel_id = Storage.get_config_value(guild, ConfigKey.WARNING_CHANNEL_ID)
 		if channel_id is None:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["info_emoji"]} No warning channel is configured.',
-				mention_author=False)
+				ephemeral=True,
+			)
 		else:
 			channel = guild.get_channel(channel_id)
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["info_emoji"]} Warning channel is configured as {channel.mention}.',
-				mention_author=False)
+				ephemeral=True,
+			)
 
 	@config.command(
-		brief='Sets a user/role to mention in warning messages',
-		usage='<@user|@role>',
-		description='Configures an role or other prefix to include at the ' +
-			'beginning of warning messages. If the intent is to get the ' +
-			'attention of certain users, be sure to specify a properly ' +
-			'formed @ tag, not just the name of the user/role.'
+		description='Sets the user or role to tag in warning messages.',
+		extras={
+			'long_description': 'Calling this without a value disables tagging in warnings.',
+		}
 	)
-	async def setwarningmention(self,
-			context: commands.Context,
-			mention: str = None) -> None:
-		"""Command handler"""
-		guild: Guild = context.guild
-		Storage.set_config_value(guild, ConfigKey.WARNING_MENTION, mention)
+	async def set_warning_mention(self,
+			interaction: Interaction,
+			mention: Optional[Union[User, Role]] = None) -> None:
+		"""
+		Sets a user/role to mention in warning messages.
+
+		Parameters
+		----------
+		interaction: Interaction
+		mention: User or Role
+			the user or role to mention in warning messages
+		"""
+		guild: Guild = interaction.guild
+		Storage.set_config_value(guild, ConfigKey.WARNING_MENTION, mention.mention if mention else None)
 		if mention is None:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["success_emoji"]} Warning messages will not tag anyone.',
-				mention_author=False)
+				ephemeral=True,
+			)
 		else:
-			await context.message.reply(
-				f'{CONFIG["success_emoji"]} Warning messages will now tag {mention}.',
-				mention_author=False)
+			await interaction.response.send_message(
+				f'{CONFIG["success_emoji"]} Warning messages will now tag {mention.mention}.',
+				ephemeral=True,
+			)
 
 	@config.command(
-		brief='Shows the user/role to mention in warning messages',
-		description='Shows the text, if any, that will be prefixed on any ' +
-			'warning messages.'
+		description='Shows the configured user or role tagged in warning messages.',
 	)
-	async def getwarningmention(self, context: commands.Context) -> None:
-		"""Command handler"""
-		guild: Guild = context.guild
+	async def get_warning_mention(self, interaction: Interaction) -> None:
+		guild: Guild = interaction.guild
 		mention: str = Storage.get_config_value(guild, ConfigKey.WARNING_MENTION)
 		if mention is None:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["info_emoji"]} No warning mention configured.',
-				mention_author=False)
+				ephemeral=True,
+			)
 		else:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["info_emoji"]} Warning messages will tag {mention}',
-				mention_author=False)
+				ephemeral=True,
+			)

rocketbot/cogs/crosspostcog.py

@@ -6,7 +6,7 @@ from datetime import datetime, timedelta, timezone
 from typing import Optional
 
 from discord import Member, Message, utils as discordutils, TextChannel
-from discord.ext import commands
+from discord.ext.commands import Cog
 
 from config import CONFIG
 from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
@@ -35,67 +35,96 @@ class CrossPostCog(BaseCog, name='Crosspost Detection'):
 	"""
 	Detects a user posting in multiple channels in a short period
 	of time: a common pattern for spammers.
-
-	These used to be identical text, but more recent attacks have had small
-	variations, such as different imgur URLs. It's reasonable to treat
-	posting in many channels in a short period as suspicious on its own,
-	regardless of whether they are identical.
-
-	Repeated posts in the same channel aren't currently detected, as this can
-	often be for a reason or due to trying a failed post when connectivity is
-	poor. Minimum message length can be enforced for detection.
 	"""
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='crosspost detection',
-		description='Whether crosspost detection is enabled.')
-	SETTING_WARN_COUNT = CogSetting('warncount', int,
+		description='Whether crosspost detection is enabled.',
+	)
+	SETTING_WARN_COUNT = CogSetting(
+		'warncount',
+		int,
+		default_value=5,
 		brief='number of messages to trigger a warning',
 		description='The number of unique channels messages are ' + \
 			'posted in by the same user to trigger a mod warning. The ' + \
 			'messages need not be identical (see dupewarncount).',
-		usage='<count:int>',
-		min_value=2)
-	SETTING_DUPE_WARN_COUNT = CogSetting('dupewarncount', int,
+		min_value=2,
+	)
+	SETTING_DUPE_WARN_COUNT = CogSetting(
+		'dupewarncount',
+		int,
+		default_value=3,
 		brief='number of identical messages to trigger a warning',
 		description='The number of unique channels identical messages are ' + \
 			'posted in by the same user to trigger a mod warning.',
-		usage='<count:int>',
-		min_value=2)
-	SETTING_BAN_COUNT = CogSetting('bancount', int,
+		min_value=2,
+	)
+	SETTING_BAN_COUNT = CogSetting(
+		'bancount',
+		int,
+		default_value=9999,
 		brief='number of messages to trigger a ban',
 		description='The number of unique channels messages are ' + \
 			'posted in by the same user to trigger an automatic ban. The ' + \
 			'messages need not be identical (see dupebancount). Set ' + \
 			'to a large value to effectively disable, e.g. 9999.',
-		usage='<count:int>',
-		min_value=2)
-	SETTING_DUPE_BAN_COUNT = CogSetting('dupebancount', int,
+		min_value=2,
+	)
+	SETTING_DUPE_BAN_COUNT = CogSetting(
+		'dupebancount',
+		int,
+		default_value=9999,
 		brief='number of identical messages to trigger a ban',
 		description='The number of unique channels identical messages are ' + \
 			'posted in by the same user to trigger an automatic ban. Set ' + \
 			'to a large value to effectively disable, e.g. 9999.',
-		usage='<count:int>',
-		min_value=2)
-	SETTING_MIN_LENGTH = CogSetting('minlength', int,
+		min_value=2,
+	)
+	SETTING_MIN_LENGTH = CogSetting(
+		'minlength',
+		int,
+		default_value=1,
 		brief='minimum message length',
 		description='The minimum number of characters in a message to be ' + \
 			'checked for duplicates. This can help ignore common short ' + \
 			'messages like "lol" or a single emoji.',
-		usage='<character_count:int>',
-		min_value=1)
-	SETTING_TIMESPAN = CogSetting('timespan', float,
+		min_value=1,
+	)
+	SETTING_TIMESPAN = CogSetting(
+		'timespan',
+		timedelta,
+		default_value=timedelta(seconds=60),
 		brief='time window to look for dupe messages',
-		description='The number of seconds of message history to look at ' + \
-			'when looking for duplicates. Shorter values are preferred, ' + \
+		description='The number of seconds of message history to look at '
+			'when looking for duplicates. Shorter values are preferred, '
 			'both to detect bots and avoid excessive memory usage.',
-		usage='<seconds:int>',
-		min_value=1)
+		min_value=timedelta(seconds=1),
+	)
 
 	STATE_KEY_RECENT_MESSAGES = "CrossPostCog.recent_messages"
 	STATE_KEY_SPAM_CONTEXT = "CrossPostCog.spam_context"
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='crosspost',
+			short_description='Manages crosspost detection and handling.',
+			long_description='Detects a user posting in multiple channels in a short period of '
+							 'time: a common pattern for spammers.\n'
+							 '\n'
+							 "These used to be identical text, but more recent attacks have had "
+							 "small variations, such as different imgur URLs. It's reasonable to "
+							 "treat posting in many channels in a short period as suspicious on its "
+							 "own, regardless of whether they are identical.\n"
+							 "\n"
+							 "Repeated posts in the same channel aren't currently detected, as "
+							 "this can often be for a reason or due to trying a failed post when "
+							 "connectivity is poor. Minimum message length can be enforced for "
+							 "detection.",
+		)
 		self.add_setting(CrossPostCog.SETTING_ENABLED)
 		self.add_setting(CrossPostCog.SETTING_WARN_COUNT)
 		self.add_setting(CrossPostCog.SETTING_DUPE_WARN_COUNT)
@@ -328,7 +357,7 @@ class CrossPostCog(BaseCog, name='Crosspost Detection'):
 		# print(message)
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_message(self, message: Message):
 		"""Event handler"""
 		if message.author is None or \
@@ -340,13 +369,3 @@ class CrossPostCog(BaseCog, name='Crosspost Detection'):
 			return
 		self.__trace("--ON MESSAGE--")
 		await self.__record_message(message)
-
-	@commands.group(
-		brief='Manages crosspost detection and handling',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def crosspost(self, context: commands.Context):
-		"""Detects members posting messages in multiple channels in a short period of time."""
-		if context.invoked_subcommand is None:
-			await context.send_help()

rocketbot/cogs/gamescog.py

@@ -0,0 +1,158 @@
+import math
+import random
+from time import perf_counter
+
+from discord import Interaction, UnfurledMediaItem
+from discord.app_commands import command, Range, guild_only
+from discord.ui import LayoutView, Section, TextDisplay, Thumbnail, Container
+
+from rocketbot.bot import Rocketbot
+from rocketbot.cogs.basecog import BaseCog
+
+
+class GamesCog(BaseCog, name="Games"):
+	"""Some really basic games or approximations thereof."""
+	def __init__(self, bot: Rocketbot):
+		super().__init__(
+			bot,
+			config_prefix='games',
+			short_description='Some stupid, low effort games.',
+		)
+
+	@command(
+		description='Rolls a die and gives the result. Provides seconds of amusement.'
+	)
+	@guild_only
+	async def roll(self, interaction: Interaction, sides: Range[int, 2, 100], share: bool = False):
+		"""
+		Rolls a die.
+
+		Parameters
+		----------
+		sides : Range[int, 2, 100]
+			how many sides on the die
+		share : bool
+			whether to show the result to everyone in chat, otherwise only shown to you
+		"""
+		result = random.randint(1, sides)
+		who = interaction.user.mention if share else 'You'
+		text = f'## :game_die: D{sides} rolled\n'\
+			   '\n'\
+			   f'    {who} rolled a **{result}**.'
+		if result == 69:
+			text += ' :smirk:'
+		if sides == 20 and result == 1:
+			text += ' :slight_frown:'
+		if sides == 20 and result == 20:
+			text += ' :tada:'
+
+		# This is a lot of work for a dumb joke
+		others = set()
+		for _ in range(min(sides - 1, 3)):
+			r = random.randint(1, sides)
+			while r in others or r == result:
+				r = random.randint(1, sides)
+			others.add(r)
+		text += f'\n\n-# Users who rolled {result} also liked {listed_items(list(others))}'
+
+		await interaction.response.send_message(text, ephemeral=not share)
+
+	@command(
+		description='Creates a really terrible Minesweeper puzzle.'
+	)
+	@guild_only
+	async def minesweeper(self, interaction: Interaction):
+		MINE = -1
+		BLANK = 0
+
+		# Generate grid
+		width, height = 8, 8  # about as big as you can get. 10x10 has too many spoiler blocks and Discord doesn't parse them.
+		mine_count = 10
+		grid = [[BLANK for _ in range(width)] for _ in range(height)]
+		all_positions = [(x, y) for y in range(height) for x in range(width)]
+
+		# Place mines randomly
+		random.shuffle(all_positions)
+		for x, y in all_positions[:mine_count]:
+			grid[x][y] = MINE
+
+		# Update free spaces with mine counts
+		for y in range(height):
+			for x in range(width):
+				if grid[x][y] == MINE:
+					continue
+				nearby_mine_count = 0
+				for y0 in range(y - 1, y + 2):
+					for x0 in range(x - 1, x + 2):
+						if 0 <= x0 < width and 0 <= y0 < height and grid[x0][y0] < 0:
+							nearby_mine_count += 1
+				grid[x][y] = nearby_mine_count
+
+		# Pick a non-mine starting tile to reveal (favoring 0s)
+		start_x, start_y = 0, 0
+		for n in range(8):
+			start_positions = [ pt for pt in all_positions if BLANK <= grid[pt[0]][pt[1]] <= n ]
+			if len(start_positions) > 0:
+				# sort by closeness to center
+				start_positions.sort(key=lambda pt: math.fabs(pt[0] - width / 2) + math.fabs(pt[1] - height / 2))
+				# pick a random one from the top 10
+				start_x, start_y = random.choice(start_positions[:10])
+				break
+
+		# Render
+		puzzle = ''
+		symbols = [
+			'\u274C',  # cross mark (red X)
+			'0\uFE0F\u20E3',  # 0 + variation selector 16 + combining enclosing keycap
+			'1\uFE0F\u20E3',
+			'2\uFE0F\u20E3',
+			'3\uFE0F\u20E3',
+			'4\uFE0F\u20E3',
+			'5\uFE0F\u20E3',
+			'6\uFE0F\u20E3',
+			'7\uFE0F\u20E3',
+			'8\uFE0F\u20E3',
+		]
+		for y in range(height):
+			puzzle += '    '
+			for x in range(width):
+				is_revealed = x == start_x and y == start_y
+				if not is_revealed:
+					puzzle += '||'
+				val = grid[x][y]
+				puzzle += symbols[val + 1]
+				if not is_revealed:
+					puzzle += '||'
+				puzzle += ' '
+			puzzle += '\n'
+
+		text = "## Minesweeper (kinda)\n"\
+			   f"Here's a really terrible randomized Minesweeper puzzle. Sorry. I did my best.¹\n"\
+			   "\n"\
+			   f"Uncover everything except the {mine_count} :x: mines. There's no game logic or anything. Just a markdown parlor trick. Police yourselves.\n"\
+			   "\n"\
+			   f"{puzzle}"\
+			   "\n"\
+			   "-# ¹ I didn't really do my best."
+		await interaction.response.send_message(
+			view=_MinesweeperLayout(text),
+			ephemeral=True,
+		)
+
+class _MinesweeperLayout(LayoutView):
+	def __init__(self, text_content: str):
+		super().__init__()
+		text = TextDisplay(text_content)
+		thumb = Thumbnail(UnfurledMediaItem('https://static.rksp.net/rocketbot/games/minesweeper/icon.png'), description='Minesweeper icon')
+		section = Section(text, accessory=thumb)
+		container = Container(section, accent_color=0xff0000)
+		self.add_item(container)
+
+def listed_items(items: list) -> str:
+	if len(items) == 0:
+		return 'nothing'
+	if len(items) == 1:
+		return f'{items[0]}'
+	if len(items) == 2:
+		return f'{items[0]} and {items[1]}'
+	return (', '.join([ str(i) for i in items[:-1]])) + f', and {items[-1]}'

rocketbot/cogs/generalcog.py

@@ -1,17 +1,18 @@
 """
 Cog for handling most ungrouped commands and basic behaviors.
 """
-import re
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from discord import Message
+from discord import Interaction, Message, User
+from discord.app_commands import command, default_permissions, guild_only, Transform
 from discord.errors import DiscordException
-from discord.ext import commands
+from discord.ext.commands import Cog
 
 from config import CONFIG
+from rocketbot.bot import Rocketbot
 from rocketbot.cogs.basecog import BaseCog, BotMessage
-from rocketbot.utils import timedelta_from_str, describe_timedelta, dump_stacktrace
+from rocketbot.utils import describe_timedelta, TimeDeltaTransformer
 from rocketbot.storage import ConfigKey, Storage
 
 class GeneralCog(BaseCog, name='General'):
@@ -19,16 +20,22 @@ class GeneralCog(BaseCog, name='General'):
 	Cog for handling high-level bot functionality and commands. Should be the
 	first cog added to the bot.
 	"""
-	def __init__(self, bot: commands.Bot):
-		super().__init__(bot)
+
+	shared: Optional['GeneralCog'] = None
+
+	def __init__(self, bot: Rocketbot):
+		super().__init__(
+			bot,
+			config_prefix=None,
+			short_description='',
+		)
 		self.is_connected = False
-		self.is_ready = False
-		self.is_first_ready = True
 		self.is_first_connect = True
 		self.last_disconnect_time: Optional[datetime] = None
 		self.noteworthy_disconnect_duration = timedelta(seconds=5)
+		GeneralCog.shared = self
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_connect(self):
 		"""Event handler"""
 		if self.is_first_connect:
@@ -41,125 +48,119 @@ class GeneralCog(BaseCog, name='General'):
 				self.log(None, f'Reconnected after {disconnect_duration.total_seconds()} seconds')
 		self.is_connected = True
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_disconnect(self):
 		"""Event handler"""
 		self.last_disconnect_time = datetime.now(timezone.utc)
 		# self.log(None, 'Disconnected')
 
-	@commands.Cog.listener()
-	async def on_ready(self):
-		"""Event handler"""
-		self.log(None, 'Bot done initializing')
-		self.is_ready = True
-		try:
-			synced_commands = await self.bot.tree.sync()
-			for command in synced_commands:
-				self.log(None, f'Synced command: {command.name}')
-		except Exception as e:
-			dump_stacktrace(e)
-		if self.is_first_ready:
-			print('----------------------------------------------------------')
-			self.is_first_ready = False
-
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_resumed(self):
 		"""Event handler"""
 		disconnect_duration = datetime.now(timezone.utc) - self.last_disconnect_time if self.last_disconnect_time else None
 		if disconnect_duration is not None and disconnect_duration > self.noteworthy_disconnect_duration:
 			self.log(None, f'Session resumed after {disconnect_duration.total_seconds()} seconds')
 
-	@commands.command(
-		brief='Posts a test warning',
-		description='Tests whether a warning channel is configured for this ' + \
-			'guild by posting a test warning. If a mod mention is ' + \
-			'configured, that user/role will be tagged in the test warning.',
+	@command(
+		description='Posts a test warning.',
+		extras={
+			'long_description': 'If a warning channel is configured, it will be posted '
+								'there. If a warning role/user is configured, they will be '
+								'tagged in the message.',
+		},
 	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def testwarn(self, context):
-		"""Command handler"""
-		if Storage.get_config_value(context.guild, ConfigKey.WARNING_CHANNEL_ID) is None:
-			await context.message.reply(
+	@guild_only()
+	@default_permissions(ban_members=True)
+	async def test_warn(self, interaction: Interaction):
+		if Storage.get_config_value(interaction.guild, ConfigKey.WARNING_CHANNEL_ID) is None:
+			await interaction.response.send_message(
 				f'{CONFIG["warning_emoji"]} No warning channel set!',
-				mention_author=False)
+				ephemeral=True,
+			)
 		else:
 			bm = BotMessage(
-				context.guild,
-				f'Test warning message (requested by {context.author.name})',
+				interaction.guild,
+				f'Test warning message (requested by {interaction.user.name})',
 				type=BotMessage.TYPE_MOD_WARNING)
 			await self.post_message(bm)
+			await interaction.response.send_message(
+				'Warning issued',
+				ephemeral=True,
+			)
 
-	@commands.command(
-		brief='Simple test reply',
-		description='Replies to the command message. Useful to ensure the ' + \
-			'bot is working properly.',
+	@command(
+		description='Responds to the user with a greeting.',
+		extras={
+			'long_description': 'Useful for checking bot responsiveness. Message '
+								'is only visible to the user.',
+		},
 	)
-	async def hello(self, context):
-		"""Command handler"""
-		await context.message.reply(
-			f'Hey, {context.author.name}!',
-		 	mention_author=False)
-
-	@commands.command(
-		brief='Shuts down the bot',
-		description='Causes the bot script to terminate. Only usable by a ' + \
-			'user with server admin permissions.',
+	async def hello(self, interaction: Interaction):
+		await interaction.response.send_message(
+			f'Hey, {interaction.user.name}!',
+		 	ephemeral=True,
+		)
+
+	@command(
+		description='Shuts down the bot.',
+		extras={
+			'long_description': 'For emergency use if the bot gains sentience. Only usable '
+								'by a server administrator.',
+		},
 	)
-	@commands.has_permissions(administrator=True)
-	@commands.guild_only()
-	async def shutdown(self, context: commands.Context):
+	@guild_only()
+	@default_permissions(administrator=True)
+	async def shutdown(self, interaction: Interaction):
 		"""Command handler"""
-		await context.message.add_reaction('👋')
+		await interaction.response.send_message('👋', ephemeral=True)
 		await self.bot.close()
 
-	@commands.command(
-		brief='Mass deletes messages',
-		description='Deletes recent messages by the given user. The user ' +
-			'can be either an @ mention or a numeric user ID. The age is ' +
-			'a duration, such as "30s", "5m", "1h30m". Only the most ' +
-			'recent 100 messages in each channel are searched.',
-		usage='<user:id|mention> <age:timespan>'
+	@command(
+		description='Mass deletes recent messages by a user.',
+		extras={
+			'long_description': 'The age is a duration, such as "30s", "5m", "1h30m", "7d". '
+								'Only the most recent 100 messages in each channel are searched.\n\n'
+								"The author can be a numeric ID if they aren't showing up in autocomplete.",
+			'usage': '<user:id|mention> <age:timespan>',
+		},
 	)
-	@commands.has_permissions(manage_messages=True)
-	@commands.guild_only()
-	async def deletemessages(self, context, user: str, age: str) -> None:
-		"""Command handler"""
-		member_id = self.__parse_member_id(user)
-		if member_id is None:
-			await context.message.reply(
-				f'{CONFIG["failure_emoji"]} user must be a mention or numeric user id',
-				mention_author=False)
-			return
-		try:
-			age_delta: timedelta = timedelta_from_str(age)
-		except ValueError:
-			await context.message.reply(
-				f'{CONFIG["failure_emoji"]} age must be a timespan, like "30s", "10m", "1h30m"',
-				mention_author=False)
-			return
-		cutoff: datetime = datetime.now(timezone.utc) - age_delta
+	@guild_only()
+	@default_permissions(manage_messages=True)
+	async def delete_messages(self, interaction: Interaction, author: User, age: Transform[timedelta, TimeDeltaTransformer]) -> None:
+		"""
+		Mass deletes messages.
+
+		Parameters
+		----------
+		interaction: :class:`Interaction`
+		author: :class:`User`
+			author of messages to delete
+		age: :class:`timedelta`
+			maximum age of messages to delete (e.g. 30s, 5m, 1h30s, 7d)
+		"""
+		member_id = author.id
+		cutoff: datetime = datetime.now(timezone.utc) - age
+
+		# Finding and deleting messages takes time but interaction needs a timely acknowledgement.
+		resp = await interaction.response.defer(ephemeral=True, thinking=True)
+
 		def predicate(message: Message) -> bool:
 			return str(message.author.id) == member_id and message.created_at >= cutoff
 		deleted_messages = []
-		for channel in context.guild.text_channels:
+		for channel in interaction.guild.text_channels:
 			try:
 				deleted_messages += await channel.purge(limit=100, check=predicate)
 			except DiscordException:
 				# XXX: Sloppily glossing over access errors instead of checking access
 				pass
-		await context.message.reply(
-			f'{CONFIG["success_emoji"]} Deleted {len(deleted_messages)} ' + \
-			f'messages by <@!{member_id}> from the past {describe_timedelta(age_delta)}.',
-			mention_author=False)
-
-	def __parse_member_id(self, arg: str) -> Optional[str]:
-		p = re.compile('^<@!?([0-9]+)>$')
-		m = p.match(arg)
-		if m:
-			return m.group(1)
-		p = re.compile('^([0-9]+)$')
-		m = p.match(arg)
-		if m:
-			return m.group(1)
-		return None
+
+		if len(deleted_messages) > 0:
+			await resp.resource.edit(
+				content=f'{CONFIG["success_emoji"]} Deleted {len(deleted_messages)} '
+						f'messages by {author.mention} from the past {describe_timedelta(age)}.',
+			)
+		else:
+			await resp.resource.edit(
+				content=f'{CONFIG["success_emoji"]} No messages found for {author.mention} '
+						'from the past {describe_timedelta(age)}.',
+			)

rocketbot/cogs/helpcog.py

@@ -0,0 +1,521 @@
+"""Provides help commands for getting info on using other commands and configuration."""
+import re
+import time
+from typing import Union, Optional, TypedDict
+
+from discord import Interaction, Permissions, AppCommandType, ButtonStyle, InteractionResponse
+from discord.app_commands import Group, Command, autocomplete, guild_only, command, Choice
+from discord.ui import ActionRow, Button, LayoutView, TextDisplay
+
+from config import CONFIG
+from rocketbot.bot import Rocketbot
+from rocketbot.cogs.basecog import BaseCog
+from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace
+
+HelpTopic = Union[Command, Group, BaseCog]
+class HelpMeta(TypedDict):
+	id: str
+	text: str
+	topic: HelpTopic
+
+# Potential place to break text neatly in large help content
+PAGE_BREAK = '\f'
+
+def choice_from_topic(topic: HelpTopic, include_full_command: bool = False) -> Choice:
+	if isinstance(topic, BaseCog):
+		return Choice(name=f'⚙ {topic.qualified_name}', value=f'cog:{topic.qualified_name}')
+	if isinstance(topic, Group):
+		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
+	if isinstance(topic, Command):
+		if topic.parent:
+			if include_full_command:
+				return Choice(name=f'/{topic.parent.name} {topic.name}', value=f'subcmd:{topic.parent.name}.{topic.name}')
+			return Choice(name=f'{topic.name}', value=f'subcmd:{topic.name}')
+		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
+	return Choice(name='', value='')
+
+async def search_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
+	try:
+		if len(current) == 0:
+			return [
+				choice_from_topic(topic, include_full_command=True)
+				for topic in HelpCog.shared.all_accessible_topics(interaction.permissions)
+			]
+		return [
+			choice_from_topic(topic, include_full_command=True)
+			for topic in HelpCog.shared.topics_for_keywords(current, interaction.permissions)
+		][:25]
+	except BaseException as e:
+		dump_stacktrace(e)
+		return []
+
+class HelpCog(BaseCog, name='Help'):
+	shared: Optional['HelpCog'] = None
+
+	def __init__(self, bot: Rocketbot):
+		super().__init__(
+			bot,
+			config_prefix='help',
+			short_description='Provides help on using this bot.'
+		)
+		HelpCog.shared = self
+
+	def __create_help_index(self) -> None:
+		"""
+		Populates self.id_to_topic and self.keyword_index. Bails if already
+		populated. Intended to be run on demand so all cogs and commands have
+		had time to get set up and synced.
+		"""
+		if getattr(self, 'id_to_topic', None) is not None:
+			return
+		self.id_to_topic: dict[str, HelpTopic] = {}
+		self.topics: list[HelpMeta] = []
+
+		def process_text(t: str) -> str:
+			return ' '.join([
+				word
+				for word in re.split(r"[^a-z']+", t.lower())
+				if word not in trivial_words
+			]).strip()
+
+		cmds = self.all_commands()
+		for cmd in cmds:
+			key = f'cmd:{cmd.name}'
+			self.id_to_topic[key] = cmd
+			self.id_to_topic[f'/{cmd.name}'] = cmd
+			text = cmd.name
+			if cmd.description:
+				text += f' {cmd.description}'
+			if cmd.extras.get('long_description', None):
+				text += f' {cmd.extras["long_description"]}'
+			self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cmd })
+			if isinstance(cmd, Group):
+				for subcmd in cmd.commands:
+					key = f'subcmd:{cmd.name}.{subcmd.name}'
+					self.id_to_topic[key] = subcmd
+					self.id_to_topic[f'/{cmd.name} {subcmd.name}'] = subcmd
+					text = cmd.name
+					text += f' {subcmd.name}'
+					if subcmd.description:
+						text += f' {subcmd.description}'
+					if subcmd.extras.get('long_description', None):
+						text += f' {subcmd.extras["long_description"]}'
+					self.topics.append({ 'id': key, 'text': process_text(text), 'topic': subcmd })
+		for cog_qname, cog in self.bot.cogs.items():
+			if not isinstance(cog, BaseCog):
+				continue
+			key = f'cog:{cog_qname}'
+			self.id_to_topic[key] = cog
+			text = cog.qualified_name
+			if cog.short_description:
+				text += f' {cog.short_description}'
+			if cog.long_description:
+				text += f' {cog.long_description}'
+			self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cog })
+
+	def topic_for_help_symbol(self, symbol: str) -> Optional[HelpTopic]:
+		self.__create_help_index()
+		return self.id_to_topic.get(symbol, None)
+
+	def all_commands(self) -> list[Union[Command, Group]]:
+		# PyCharm not interpreting conditional return type correctly.
+		# noinspection PyTypeChecker
+		cmds: list[Union[Command, Group]] = self.bot.tree.get_commands(type=AppCommandType.chat_input)
+		return sorted(cmds, key=lambda cmd: cmd.name)
+
+	def all_accessible_commands(self, permissions: Optional[Permissions]) -> list[Union[Command, Group]]:
+		return [
+			cmd
+			for cmd in self.all_commands()
+			if can_use_command(cmd, permissions)
+		]
+
+	def all_accessible_subcommands(self, permissions: Optional[Permissions]) -> list[Command]:
+		cmds = self.all_accessible_commands(permissions)
+		subcmds: list[Command] = []
+		for cmd in cmds:
+			if isinstance(cmd, Group):
+				for subcmd in sorted(cmd.commands, key=lambda cmd: cmd.name):
+					if can_use_command(subcmd, permissions):
+						subcmds.append(subcmd)
+		return subcmds
+
+	def all_accessible_cogs(self, permissions: Optional[Permissions]) -> list[BaseCog]:
+		return [
+			cog
+			for cog in self.basecogs
+			if can_use_cog(cog, permissions)
+		]
+
+	def all_accessible_topics(self, permissions: Optional[Permissions], *,
+							  include_cogs: bool = True,
+							  include_commands: bool = True,
+							  include_subcommands: bool = True) -> list[HelpTopic]:
+		topics = []
+		if include_cogs:
+			topics += self.all_accessible_cogs(permissions)
+		if include_commands:
+			topics += self.all_accessible_commands(permissions)
+		if include_subcommands:
+			topics += self.all_accessible_subcommands(permissions)
+		return topics
+
+	def topics_for_keywords(self, search: str, permissions: Optional[Permissions]) -> list[HelpTopic]:
+		start_time = time.perf_counter()
+		self.__create_help_index()
+
+		# Break into words (or word fragments)
+		words: list[str] = [
+			word
+			for word in re.split(r"[^a-z']+", search.lower())
+		]
+
+		# Find matches
+		def topic_matches(meta: HelpMeta) -> bool:
+			for word in words:
+				if word not in meta['text']:
+					return False
+			return True
+		matching_topics: list[HelpTopic] = [ topic['topic'] for topic in self.topics if topic_matches(topic) ]
+
+		# Filter by accessibility
+		accessible_topics = [
+			topic
+			for topic in matching_topics
+			if ((isinstance(topic, Command) or isinstance(topic, Group)) and can_use_command(topic, permissions)) or \
+			   (isinstance(topic, BaseCog) and can_use_cog(topic, permissions))
+		]
+
+		# Sort and return
+		result = sorted(accessible_topics, key=lambda topic: (
+			isinstance(topic, Command),
+			isinstance(topic, BaseCog),
+			topic.qualified_name if isinstance(topic, BaseCog) else topic.name
+		))
+		duration = time.perf_counter() - start_time
+		if duration > 0.01:
+			self.log(None, f'search "{search}" took {duration} seconds')
+		return result
+
+	@command(
+		name='help',
+		description='Shows help for using commands and module configuration.',
+		extras={
+			'long_description': '`/help` will show a list of top-level topics.\n'
+								'\n'
+								"`/help /<command_name>` will show help about a specific command or list a command's subcommands.\n"
+								'\n'
+								'`/help /<command_name> <subcommand_name>` will show help about a specific subcommand.\n'
+								'\n'
+								'`/help <module_name>` will show help about configuring a module.\n'
+								'\n'
+								'`/help <keywords>` will do a text search for topics.',
+		}
+	)
+	@guild_only()
+	@autocomplete(search=search_autocomplete)
+	async def help_command(self, interaction: Interaction, search: Optional[str]) -> None:
+		"""
+		Shows help for using commands and subcommands and configuring modules.
+
+		Parameters
+		----------
+		interaction: Interaction
+		search: Optional[str]
+			search terms
+		"""
+		if search is None:
+			await self.__send_general_help(interaction)
+			return
+		topic = self.topic_for_help_symbol(search)
+		if topic:
+			await self.__send_topic_help(interaction, topic)
+			return
+		matches = self.topics_for_keywords(search, interaction.permissions)
+		await self.__send_keyword_help(interaction, matches)
+
+	async def __send_topic_help(self, interaction: Interaction, topic: HelpTopic) -> None:
+		if isinstance(topic, Command):
+			await self.__send_command_help(interaction, topic)
+			return
+		if isinstance(topic, Group):
+			await self.__send_command_help(interaction, topic)
+			return
+		if isinstance(topic, BaseCog):
+			await self.__send_cog_help(interaction, topic)
+			return
+		self.log(interaction.guild, f'No help for topic object {topic}')
+		await interaction.response.send_message(
+			f'{CONFIG["failure_emoji"]} Failed to get help info.',
+			ephemeral=True,
+			delete_after=10,
+		)
+
+	def get_command_list(self, permissions: Optional[Permissions] = None) -> dict[str, Union[Command, Group]]:
+		return { cmd.name: cmd for cmd in self.bot.tree.get_commands() if can_use_command(cmd, permissions) }
+
+	def get_subcommand_list(self, cmd: Group, permissions: Optional[Permissions] = None) -> dict[str, Command]:
+		return {
+			subcmd.name: subcmd
+			for subcmd in cmd.commands
+			if can_use_command(subcmd, permissions)
+		} if can_use_command(cmd, permissions) else {}
+
+	async def __send_general_help(self, interaction: Interaction) -> None:
+		user_permissions: Permissions = interaction.permissions
+		all_commands = sorted(self.get_command_list(user_permissions).items())
+		all_cog_tuples: list[tuple[str, BaseCog]] = [
+			cog_tuple
+			for cog_tuple in sorted(self.basecog_map.items())
+			if can_use_cog(cog_tuple[1], user_permissions) and \
+			   (len(cog_tuple[1].settings) > 0)
+		]
+
+		text = f'## :information_source: Help'
+		if len(all_commands) + len(all_cog_tuples) == 0:
+			text = 'Nothing available for your permissions!'
+
+		if len(all_commands) > 0:
+			text += '\n### Commands'
+			text += '\nType `/help /commandname` for more information.'
+			for cmd_name, cmd in sorted(self.get_command_list(user_permissions).items()):
+				text += f'\n- `/{cmd_name}`: {cmd.description}'
+				if isinstance(cmd, Group):
+					subcommand_count = len(cmd.commands)
+					text += f' ({subcommand_count} subcommands)'
+			text += PAGE_BREAK
+
+		if len(all_cog_tuples) > 0:
+			text += '\n### Module Configuration'
+			for cog_name, cog in all_cog_tuples:
+				has_enabled = next((s for s in cog.settings if s.name == 'enabled'), None) is not None
+				text += f'\n- **{cog_name}**: {cog.short_description}'
+				if has_enabled:
+					text += f'\n   - `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`'
+				for setting in cog.settings:
+					if setting.name == 'enabled':
+						continue
+					text += f'\n   - `/get` or `/set {cog.config_prefix}_{setting.name}`'
+				text += PAGE_BREAK
+
+		await self.__send_paged_help(interaction, text)
+
+	async def __send_keyword_help(self, interaction: Interaction, matching_topics: Optional[list[HelpTopic]]) -> None:
+		matching_commands = [
+			cmd
+			for cmd in matching_topics or []
+			if isinstance(cmd, Command) or isinstance(cmd, Group)
+		]
+		matching_cogs = [
+			cog
+			for cog in matching_topics or []
+			if isinstance(cog, BaseCog)
+		]
+		if len(matching_commands) + len(matching_cogs) == 0:
+			await interaction.response.send_message(
+				f'{CONFIG["failure_emoji"]} No available help topics found.',
+				ephemeral=True,
+				delete_after=10,
+			)
+			return
+		if len(matching_topics) == 1:
+			topic = matching_topics[0]
+			await self.__send_topic_help(interaction, topic)
+			return
+
+		text = '## :information_source: Matching Help Topics'
+		if len(matching_commands) > 0:
+			text += '\n### Commands'
+			for cmd in matching_commands:
+				if cmd.parent:
+					text += f'\n- `/{cmd.parent.name} {cmd.name}`'
+				else:
+					text += f'\n- `/{cmd.name}`'
+		if len(matching_cogs) > 0:
+			text += '\n### Modules'
+			for cog in matching_cogs:
+				text += f'\n- {cog.qualified_name}'
+
+		await self.__send_paged_help(interaction, text)
+
+	async def __send_command_help(self, interaction: Interaction, command_or_group: Union[Command, Group], addendum: Optional[str] = None) -> None:
+		text = ''
+		if addendum is not None:
+			text += addendum + '\n\n'
+		if command_or_group.parent:
+			text += f'## :information_source: Subcommand Help'
+			text += f'\n`/{command_or_group.parent.name} {command_or_group.name}`'
+		else:
+			text += f'## :information_source: Command Help'
+			if isinstance(command_or_group, Group):
+				text += f'\n`/{command_or_group.name} subcommand_name`'
+			else:
+				text += f'\n`/{command_or_group.name}`'
+		if isinstance(command_or_group, Command):
+			optional_nesting = 0
+			for param in command_or_group.parameters:
+				text += '  '
+				if not param.required:
+					text += '['
+					optional_nesting += 1
+				text += f'_{param.name}_'
+			if optional_nesting > 0:
+				text += ']' * optional_nesting
+		text += f'\n\n{command_or_group.description}'
+		if command_or_group.extras.get('long_description'):
+			text += f'\n\n{command_or_group.extras["long_description"]}'
+		if isinstance(command_or_group, Group):
+			subcmds: dict[str, Command] = self.get_subcommand_list(command_or_group, permissions=interaction.permissions)
+			if len(subcmds) > 0:
+				text += '\n### Subcommands:'
+				for subcmd_name, subcmd in sorted(subcmds.items()):
+					text += f'\n- `{subcmd_name}`: {subcmd.description}'
+				text += f'\n-# To use a subcommand, type it after the command. e.g. `/{command_or_group.name} subcommand_name`'
+				text += f'\n-# Get help on a subcommand by typing `/help /{command_or_group.name} subcommand_name`'
+		else:
+			params = command_or_group.parameters
+			if len(params) > 0:
+				text += '\n### Parameters:'
+				for param in params:
+					text += f'\n- `{param.name}`: {param.description}'
+					if not param.required:
+						text += ' (optional)'
+
+		await self.__send_paged_help(interaction, text)
+
+	async def __send_cog_help(self, interaction: Interaction, cog: BaseCog) -> None:
+		text = f'## :information_source: Module Help'
+		text += f'\n**{cog.qualified_name}** module'
+		if cog.short_description is not None:
+			text += f'\n\n{cog.short_description}'
+		if cog.long_description is not None:
+			text += f'\n\n{cog.long_description}'
+
+		cmds = [
+			cmd
+			for cmd in sorted(cog.get_app_commands(), key=lambda c: c.name)
+			if can_use_command(cmd, interaction.permissions)
+		]
+		if len(cmds) > 0:
+			text += '\n### Commands:'
+			for cmd in cmds:
+				text += f'\n- `/{cmd.name}` - {cmd.description}'
+				if isinstance(cmd, Group):
+					subcmds = [ subcmd for subcmd in cmd.commands if can_use_command(subcmd, interaction.permissions) ]
+					if len(subcmds) > 0:
+						text += f' ({len(subcmds)} subcommands)'
+
+		settings = cog.settings
+		if len(settings) > 0:
+			text += '\n### Configuration'
+			enabled_setting = next((s for s in settings if s.name == 'enabled'), None)
+			if enabled_setting is not None:
+				text += f'\n- `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`'
+			for setting in sorted(settings, key=lambda s: s.name):
+				if setting.name == 'enabled':
+					continue
+				text += f'\n- `/get` or `/set {cog.config_prefix}_{setting.name}` - {setting.brief}'
+
+		await self.__send_paged_help(interaction, text)
+
+	async def __send_paged_help(self, interaction: Interaction, text: str) -> None:
+		pages = _paginate(text)
+		if len(pages) == 1:
+			await interaction.response.send_message(pages[0], ephemeral=True)
+		else:
+			await _update_paged_help(interaction, None, 0, pages)
+
+def _paginate(text: str) -> list[str]:
+	max_page_size = 2000
+	chunks = text.split(PAGE_BREAK)
+	pages = [ '' ]
+	for chunk in chunks:
+		if len(chunk) > max_page_size:
+			raise ValueError('Help content needs more page breaks! One chunk is too big for message.')
+		if len(pages[-1] + chunk) < max_page_size:
+			pages[-1] += chunk
+		else:
+			pages.append(chunk)
+	page_count = len(pages)
+	if page_count == 1:
+		return pages
+
+	# Do another pass and try to even out the page lengths
+	indices = [ i * len(chunks) // page_count for i in range(page_count + 1) ]
+	even_pages = [
+		''.join(chunks[indices[i]:indices[i + 1]])
+		for i in range(page_count)
+	]
+	for page in even_pages:
+		if len(page) > max_page_size:
+			# We made a page too big. Give up.
+			return pages
+	return even_pages
+
+async def _update_paged_help(interaction: Interaction, original_interaction: Optional[Interaction], current_page: int, pages: list[str]) -> None:
+	try:
+		view = _PagingLayoutView(current_page, pages, original_interaction or interaction)
+		resolved = interaction
+		if original_interaction is not None:
+			# We have an original interaction from the initial command and a
+			# new one from the button press. Use the original to swap in the
+			# new page in place, then acknowledge the new one to satisfy the
+			# API that we didn't fail.
+			await original_interaction.edit_original_response(
+				view=view,
+			)
+			if interaction is not original_interaction:
+				await interaction.response.defer(ephemeral=True, thinking=False)
+		else:
+			# Initial send
+			await resolved.response.send_message(
+				view=view,
+				ephemeral=True,
+				delete_after=60,
+			)
+	except BaseException as e:
+		dump_stacktrace(e)
+
+class _PagingLayoutView(LayoutView):
+	def __init__(self, current_page: int, pages: list[str], original_interaction: Optional[Interaction]):
+		super().__init__()
+		self.current_page: int = current_page
+		self.pages: list[str] = pages
+		self.text.content = self.pages[self.current_page]
+		self.original_interaction = original_interaction
+		if current_page <= 0:
+			self.handle_prev_button.disabled = True
+		if current_page >= len(self.pages) - 1:
+			self.handle_next_button.disabled = True
+
+	text = TextDisplay('')
+
+	row = ActionRow()
+
+	@row.button(label='< Prev')
+	async def handle_prev_button(self, interaction: Interaction, button: Button) -> None:
+		new_page = max(0, self.current_page - 1)
+		await _update_paged_help(interaction, self.original_interaction, new_page, self.pages)
+
+	@row.button(label='Next >')
+	async def handle_next_button(self, interaction: Interaction, button: Button) -> None:
+		new_page = min(len(self.pages) - 1, self.current_page + 1)
+		await _update_paged_help(interaction, self.original_interaction, new_page, self.pages)
+
+# Exclusions from keyword indexing
+trivial_words = {
+	'a', 'an', 'and', 'are', "aren't", 'as', 'by', 'can', 'for', 'have', 'if', 'in',
+	'is', 'it', 'its', "it's", 'not', 'of', 'on', 'or', 'than', 'that', 'the', 'then',
+	'there', 'them', 'they', "they're", 'this', 'to', 'when', 'with',
+}
+
+def can_use_command(cmd: Union[Group, Command], user_permissions: Optional[Permissions]) -> bool:
+	if user_permissions is None:
+		return False
+	if cmd.parent and not can_use_command(cmd.parent, user_permissions):
+		return False
+	return cmd.default_permissions is None or cmd.default_permissions.is_subset(user_permissions)
+
+def can_use_cog(cog: BaseCog, user_permissions: Optional[Permissions]) -> bool:
+	# "Using" a cog for now means configuring it, and only mods can configure cogs.
+	return user_permissions is not None and MOD_PERMISSIONS.is_subset(user_permissions)

rocketbot/cogs/joinagecog.py

@@ -1,150 +0,0 @@
-import weakref
-
-from datetime import datetime, timedelta, timezone
-from discord import Guild, Member
-from discord.ext import commands
-
-from config import CONFIG
-from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
-from rocketbot.collections import AgeBoundList
-from rocketbot.storage import Storage
-from rocketbot.utils import timedelta_from_str
-
-class JoinAgeQueryContext:
-	"""
-	Data about a join age query
-	"""
-	def __init__(self, join_members: list, timespan: str):
-		self.join_members = list(join_members)
-		self.timespan = timespan
-		self.kicked_members = set()
-		self.banned_members = set()
-		self.results_message_ref = None
-
-class JoinAgeCog(BaseCog, name='Join Age'):
-	"""
-	Cog for finding users by when they joined.
-	"""
-	SETTING_ENABLED = CogSetting('enabled', bool,
-		brief='join age',
-		description='Whether this cog is enabled for a guild.')
-	SETTING_JOIN_TIME = CogSetting('jointime', float,
-		brief='maximum length of time to track new joins',
-		description='The number of seconds of join history to maintain.',
-		usage='<seconds:float>',
-		min_value=1.0)
-
-	STATE_KEY_RECENT_JOINS = "JoinAgeCog.recent_joins"
-
-	def __init__(self, bot):
-		super().__init__(bot)
-		self.add_setting(JoinAgeCog.SETTING_ENABLED)
-		self.add_setting(JoinAgeCog.SETTING_JOIN_TIME)
-
-	@commands.group(
-		brief='Tracks recently joined users with options to mass kick or ban',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def joinage(self, context: commands.Context):
-		"""Join age tracking"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
-	@joinage.command(
-		brief='Queries for users who joined in the past span of time',
-		description='Searches for users who joined the server recently. ' + \
-			'Can use time spans like 30s, 5m, 1h, 7d, etc.',
-		usage='<time_period>'
-	)
-	async def search(self, context: commands.Context, timespan: str):
-		"""Command handler"""
-		guild: Guild = context.guild
-		recent_joins: AgeBoundList[Member, datetime, timedelta] = Storage.get_state_value(guild, self.STATE_KEY_RECENT_JOINS)
-		if recent_joins is None:
-			max_age: timedelta = timedelta(seconds=self.get_guild_setting(guild, self.SETTING_JOIN_TIME))
-			recent_joins = AgeBoundList(max_age, lambda i, member0 : member0.joined_at)
-			Storage.set_state_value(guild, self.STATE_KEY_RECENT_JOINS, recent_joins)
-		results: list = []
-		ts: timedelta = timedelta_from_str(timespan)
-		cutoff: datetime = datetime.now(timezone.utc) - ts
-		for member in recent_joins:
-			if member.joined_at > cutoff:
-				results.append(member)
-		ctx = JoinAgeQueryContext(results, timespan)
-		msg = BotMessage(guild,
-						text='',
-						type=BotMessage.TYPE_INFO,
-						context=ctx)
-		ctx.results_message_ref = weakref.ref(msg)
-		await self.__update_results_message(ctx)
-		await self.post_message(msg)
-
-	async def on_mod_react(self,
-			bot_message: BotMessage,
-			reaction: BotMessageReaction,
-			reacted_by: Member) -> None:
-		guild: Guild = bot_message.guild
-		ctx: JoinAgeQueryContext = bot_message.context
-		if reaction.emoji == CONFIG['kick_emoji']:
-			to_kick = set(ctx.join_members) - ctx.kicked_members
-			for member in to_kick:
-				await member.kick(
-					reason=f'Rocketbot: Mass kick based on join age, by {reacted_by.name}.')
-			ctx.kicked_members |= to_kick
-			await self.__update_results_message(ctx)
-			self.log(guild, f'Users kicked by {reacted_by.name}.')
-		elif reaction.emoji == CONFIG['ban_emoji']:
-			to_ban = set(ctx.join_members) - ctx.banned_members
-			for member in to_ban:
-				await member.ban(
-					reason=f'Rocketbot: Mass ban based on join age, by {reacted_by.name}.',
-					delete_message_days=0)
-			ctx.banned_members |= to_ban
-			await self.__update_results_message(ctx)
-			self.log(guild, f'Users banned by {reacted_by.name}')
-
-	@commands.Cog.listener()
-	async def on_member_join(self, member: Member) -> None:
-		"""Event handler"""
-		guild: Guild = member.guild
-		if not self.get_guild_setting(guild, self.SETTING_ENABLED):
-			return
-		recent_joins: AgeBoundList[Member, datetime, timedelta] = Storage.get_state_value(guild, self.STATE_KEY_RECENT_JOINS)
-		if recent_joins is None:
-			max_age: timedelta = timedelta(seconds=self.get_guild_setting(guild, self.SETTING_JOIN_TIME))
-			recent_joins = AgeBoundList(max_age, lambda i, member : member.joined_at)
-			Storage.set_state_value(guild, self.STATE_KEY_RECENT_JOINS, recent_joins)
-		recent_joins.append(member)
-
-	async def __update_results_message(self, context: JoinAgeQueryContext) -> None:
-		if context.results_message_ref is None:
-			return
-		bot_message = context.results_message_ref()
-		if bot_message is None:
-			return
-		text = f'The following members joined in the last {context.timespan}\n\n'
-		if len(context.join_members) > 0:
-			max_members = CONFIG['max_members_per_message']
-			for member in context.join_members[:max_members]:
-				text += '\n• '
-				if member in context.banned_members:
-					text += f'~~{member.mention} ({member.id})~~ - banned'
-				elif member in context.kicked_members:
-					text += f'~~{member.mention} ({member.id})~~ - kicked'
-				else:
-					text += f'{member.mention} ({member.id})'
-			if len(context.join_members) > max_members:
-				text += f'\n• {len(context.join_members) - max_members} more'
-		else:
-			text += 'No members found. If the bot was recently restarted ' + \
-				'or JoinAgeCog just enabled, only new joins will be tracked.'
-		await bot_message.set_text(text)
-		if len(context.join_members) > 0:
-			member_count = len(context.join_members)
-			kick_count = len(context.kicked_members)
-			ban_count = len(context.banned_members)
-			await bot_message.set_reactions(BotMessageReaction.standard_set(
-				did_kick=kick_count >= member_count,
-				did_ban=ban_count >= member_count,
-				user_count=member_count))

rocketbot/cogs/joinraidcog.py

@@ -4,7 +4,7 @@ Cog for detecting large numbers of guild joins in a short period of time.
 import weakref
 from datetime import datetime, timedelta
 from discord import Guild, Member
-from discord.ext import commands
+from discord.ext.commands import Cog
 
 from config import CONFIG
 from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
@@ -29,43 +29,50 @@ class JoinRaidCog(BaseCog, name='Join Raids'):
 	"""
 	Cog for monitoring member joins and detecting potential bot raids.
 	"""
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='join raid detection',
-			description='Whether this cog is enabled for a guild.')
-	SETTING_JOIN_COUNT = CogSetting('joincount', int,
+		description='Whether this module is enabled for a guild.',
+	)
+	SETTING_JOIN_COUNT = CogSetting(
+		'joincount',
+		int,
+		default_value=5,
 		brief='number of joins to trigger a warning',
-			description='The number of joins occuring within the time ' + \
+		description='The number of joins occurring within the time '
 					'window to trigger a mod warning.',
-			usage='<count:int>',
-			min_value=2)
-	SETTING_JOIN_TIME = CogSetting('jointime', float,
+		min_value=2,
+	)
+	SETTING_JOIN_TIME = CogSetting(
+		'jointime',
+		timedelta,
+		default_value=timedelta(seconds=5),
 		brief='time window length to look for joins',
-			description='The number of seconds of join history to look ' + \
-				'at when counting recent joins. If joincount or more ' + \
+		description='The number of seconds of join history to look '
+					'at when counting recent joins. If joincount or more '
 				    'joins occur within jointime seconds a mod warning is issued.',
-			usage='<seconds:float>',
-			min_value=1.0,
-			max_value=900.0)
+		min_value=timedelta(seconds=1.0),
+		max_value=timedelta(seconds=900.0),
+	)
 
 	STATE_KEY_RECENT_JOINS = "JoinRaidCog.recent_joins"
 	STATE_KEY_LAST_RAID = "JoinRaidCog.last_raid"
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='joinraid',
+			short_description='Manages join raid detection and handling.',
+			long_description='Join raids consist of an unusual number of users joining in '
+							 'a short period of time and have shown a pattern of DMing '
+							 'members with spam or scams.'
+		)
 		self.add_setting(JoinRaidCog.SETTING_ENABLED)
 		self.add_setting(JoinRaidCog.SETTING_JOIN_COUNT)
 		self.add_setting(JoinRaidCog.SETTING_JOIN_TIME)
 
-	@commands.group(
-		brief='Manages join raid detection and handling',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def joinraid(self, context: commands.Context):
-		"""Join raid detection command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
 	async def on_mod_react(self,
 			bot_message: BotMessage,
 			reaction: BotMessageReaction,
@@ -90,7 +97,7 @@ class JoinRaidCog(BaseCog, name='Join Raids'):
 			await self.__update_warning_message(raid)
 			self.log(guild, f'Join raid users banned by {reacted_by.name}')
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_join(self, member: Member) -> None:
 		"""Event handler"""
 		guild: Guild = member.guild

rocketbot/cogs/logcog.py

@@ -2,11 +2,12 @@
 Cog for detecting large numbers of guild joins in a short period of time.
 """
 from collections.abc import Sequence
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timedelta, timezone
 
 from discord import AuditLogAction, AuditLogEntry, Emoji, Guild, GuildSticker, Invite, Member, Message, RawBulkMessageDeleteEvent, RawMessageDeleteEvent, RawMessageUpdateEvent, Role, Thread, User
 from discord.abc import GuildChannel
-from discord.ext import commands, tasks
+from discord.ext import tasks
+from discord.ext.commands import Cog
 from discord.utils import escape_markdown
 from typing import Optional, Tuple, Union, Callable
 import difflib
@@ -37,14 +38,22 @@ class LoggingCog(BaseCog, name='Logging'):
 	"""
 	Cog for logging notable events to a designated logging channel.
 	"""
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='logging',
-			description='Whether this cog is enabled for a guild.')
+		description='Whether this module is enabled for a guild.',
+	)
 
 	STATE_EVENT_BUFFER = 'LoggingCog.eventBuffer'
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='logging',
+			short_description='Manages event logging.',
+		)
 		self.add_setting(LoggingCog.SETTING_ENABLED)
 		self.flush_buffers.start()
 		self.buffered_guilds: set[Guild] = set()
@@ -52,19 +61,9 @@ class LoggingCog(BaseCog, name='Logging'):
 	def cog_unload(self) -> None:
 		self.flush_buffers.cancel()
 
-	@commands.group(
-		brief='Manages event logging',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def logging(self, context: commands.Context):
-		"""Logging command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
 	# Events - Channels
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_channel_delete(self, channel: GuildChannel) -> None:
 		"""
 		Called whenever a guild channel is deleted or created.
@@ -80,7 +79,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_channel_create(self, channel: GuildChannel) -> None:
 		"""
 		Called whenever a guild channel is deleted or created.
@@ -96,7 +95,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_channel_update(self, before: GuildChannel, after: GuildChannel) -> None:
 		"""
 		Called whenever a guild channel is updated. e.g. changed name, topic,
@@ -129,27 +128,27 @@ class LoggingCog(BaseCog, name='Logging'):
 
 	# Events - Guilds
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_available(self, guild: Guild) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_unavailable(self, guild: Guild) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_update(self, before: Guild, after: Guild) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_emojis_update(self, guild: Guild, before: Sequence[Emoji], after: Sequence[Emoji]) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_stickers_update(self, guild: Guild, before: Sequence[GuildSticker], after: Sequence[GuildSticker]) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_invite_create(self, invite: Invite) -> None:
 		"""
 		Called when an `Invite` is created. You must have manage_channels to receive this.
@@ -167,7 +166,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_invite_delete(self, invite: Invite) -> None:
 		"""
 		Called when an `Invite` is deleted. You must have manage_channels to receive this.
@@ -186,7 +185,7 @@ class LoggingCog(BaseCog, name='Logging'):
 
 	# Events - Members
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_join(self, member: Member) -> None:
 		"""
 		Called when a Member joins a Guild.
@@ -250,7 +249,7 @@ class LoggingCog(BaseCog, name='Logging'):
 			bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_remove(self, member: Member) -> None:
 		"""
 		Called when a Member leaves a Guild.
@@ -284,7 +283,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_update(self, before: Member, after: Member) -> None:
 		"""
 		Called when a Member updates their profile.
@@ -346,7 +345,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_user_update(self, before: User, after: User) -> None:
 		"""
 		Called when a User updates their profile.
@@ -378,7 +377,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_ban(self, guild: Guild, user: Union[User, Member]) -> None:
 		"""
 		Called when user gets banned from a Guild.
@@ -419,7 +418,7 @@ class LoggingCog(BaseCog, name='Logging'):
 				return entry
 		return None
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_unban(self, guild: Guild, user: Union[User, Member]) -> None:
 		"""
 		Called when a User gets unbanned from a Guild.
@@ -472,7 +471,7 @@ class LoggingCog(BaseCog, name='Logging'):
 	async def before_flush_buffers_start(self) -> None:
 		await self.bot.wait_until_ready()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_message(self, message: Message) -> None:
 		"""
 		Called when a Message is created and sent.
@@ -481,7 +480,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		"""
 		# print(f"Saw message {message.id} \"{message.content}\"")
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_message_edit(self, before: Message, after: Message) -> None:
 		"""
 		Called when a Message receives an update event. If the message is not
@@ -512,7 +511,7 @@ class LoggingCog(BaseCog, name='Logging'):
 
 		self.__buffer_event(guild, 'edit', BufferedMessageEditEvent(guild, channel, before, after))
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_raw_message_edit(self, payload: RawMessageUpdateEvent) -> None:
 		"""
 		Called when a message is edited. Unlike on_message_edit(), this is called
@@ -632,7 +631,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG, suppress_embeds=True)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_raw_message_delete(self, payload: RawMessageDeleteEvent) -> None:
 		"""
 		Called when a message is deleted. Unlike on_message_delete(), this is
@@ -660,7 +659,7 @@ class LoggingCog(BaseCog, name='Logging'):
 			return
 		self.__buffer_event(guild, 'delete', BufferedMessageDeleteEvent(guild, channel, payload.message_id, message))
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_raw_bulk_message_delete(self, payload: RawBulkMessageDeleteEvent) -> None:
 		"""
 		Called when a bulk delete is triggered. Unlike on_bulk_message_delete(),
@@ -740,7 +739,7 @@ class LoggingCog(BaseCog, name='Logging'):
 
 	# Events - Roles
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_role_create(self, role: Role) -> None:
 		"""
 		Called when a Guild creates or deletes a new Role.
@@ -756,7 +755,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_role_delete(self, role: Role) -> None:
 		"""
 		Called when a Guild creates or deletes a new Role.
@@ -772,7 +771,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bot_message = BotMessage(guild, text, BotMessage.TYPE_LOG)
 		await bot_message.update()
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_guild_role_update(self, before: Role, after: Role) -> None:
 		"""
 		Called when a Role is changed guild-wide.
@@ -815,15 +814,15 @@ class LoggingCog(BaseCog, name='Logging'):
 
 	# Events - Threads
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_thread_create(self, thread: Thread) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_thread_update(self, before: Thread, after: Thread) -> None:
 		pass
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_thread_delete(self, thread: Thread) -> None:
 		pass
 

rocketbot/cogs/patterncog.py

@@ -2,18 +2,23 @@
 Cog for matching messages against guild-configurable criteria and taking
 automated actions on them.
 """
+import re
 from datetime import datetime
 from typing import Optional
 
-from discord import Guild, Member, Message, utils as discordutils
-from discord.ext import commands
+from discord import Guild, Member, Message, utils as discordutils, Interaction
+from discord.app_commands import Choice, Group, autocomplete
+from discord.ext.commands import Cog
 
 from config import CONFIG
+from rocketbot.bot import Rocketbot
 from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction
 from rocketbot.cogsetting import CogSetting
 from rocketbot.pattern import PatternCompiler, PatternDeprecationError, \
 	PatternError, PatternStatement
 from rocketbot.storage import Storage
+from rocketbot.utils import dump_stacktrace, MOD_PERMISSIONS
+
 
 class PatternContext:
 	"""
@@ -27,15 +32,106 @@ class PatternContext:
 		self.is_kicked = False
 		self.is_banned = False
 
+async def pattern_name_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
+	choices: list[Choice[str]] = []
+	try:
+		if interaction.guild is None:
+			return []
+		patterns: dict[str, PatternStatement] = PatternCog.shared.get_patterns(interaction.guild)
+		current_normal = current.lower().strip()
+		for name in sorted(patterns.keys()):
+			if len(current_normal) == 0 or current_normal.startswith(name.lower()):
+				choices.append(Choice(name=name, value=name))
+	except BaseException as e:
+		dump_stacktrace(e)
+	return choices
+
+async def action_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
+	# FIXME: WORK IN PROGRESS
+	print(f'autocomplete action - current = "{current}"')
+	regex = re.compile('^(.*?)([a-zA-Z]+)$')
+	match: Optional[re.Match[str]] = regex.match(current)
+	initial: str = ''
+	stub: str = current
+	if match:
+		initial = match.group(1).strip()
+		stub = match.group(2)
+	if PatternCompiler.ACTION_TO_ARGS.get(stub, None) is not None:
+		# Matches perfectly. Suggest another instead of completing the current.
+		initial = current.strip() + ', '
+		stub = ''
+	print(f'initial = "{initial}", stub = "{stub}"')
+
+	options: list[Choice[str]] = []
+	for action in sorted(PatternCompiler.ACTION_TO_ARGS.keys()):
+		if len(stub) == 0 or action.startswith(stub.lower()):
+			arg_types = PatternCompiler.ACTION_TO_ARGS[action]
+			arg_type_strs = []
+			for arg_type in arg_types:
+				if arg_type == PatternCompiler.TYPE_TEXT:
+					arg_type_strs.append('"message"')
+				else:
+					raise ValueError(f'Argument type {arg_type} not yet supported')
+			suffix = '' if len(arg_type_strs) == 0 else ' ' + (' '.join(arg_type_strs))
+			options.append(Choice(name=action, value=f'{initial.strip()} {action}{suffix}'))
+	return options
+
+async def priority_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
+	return [
+		Choice(name='very low (50)', value=50),
+		Choice(name='low (75)', value=75),
+		Choice(name='normal (100)', value=100),
+		Choice(name='high (125)', value=125),
+		Choice(name='very high (150)', value=150),
+	]
+
+_long_help = \
+"""Patterns are a powerful but complex topic. See <https://git.rixafrix.com/ialbert/python-app-rocketbot/src/branch/main/docs/patterns.md> for full documentation.
+
+### Quick cheat sheet
+
+> `/pattern add` _pattern\\_name_ _action\\_list_ `if` _expression_
+
+- _pattern\\_name_ is a brief name for identifying the pattern later (not shown to user)
+- _action\\_list_ is a comma-delimited list of actions to take on matching messages and is any of:
+   - `ban`
+   - `delete`
+   - `kick`
+   - `modinfo` - logs a message but doesn't tag mods
+   - `modwarn` - tags mods
+   - `reply` "message text"
+- _expression_ determines which messages match, of the form _field_ _op_ _value_.
+   - Fields:
+      - `content.markdown`: string
+      - `content.plain`: string
+      - `author`: user
+      - `author.id`: id
+      - `author.joinage`: timespan
+      - `author.name`: string
+      - `lastmatched`: timespan
+   - Operators: `==`, `!=`, `<`, `>`, `<=`, `>=`, `contains`, `!contains`, `matches`, `!matches`, `containsword`, `!containsword`
+   - Can combine multiple expressions with `!`, `and`, `or`, and parentheses."""
+
 class PatternCog(BaseCog, name='Pattern Matching'):
 	"""
 	Highly flexible cog for performing various actions on messages that match
 	various criteria. Patterns can be defined by mods for each guild.
 	"""
 
-	SETTING_PATTERNS = CogSetting('patterns', None)
+	SETTING_PATTERNS = CogSetting('patterns', None, default_value=None)
+
+	shared: Optional['PatternCog'] = None
 
-	def __get_patterns(self, guild: Guild) -> dict[str, PatternStatement]:
+	def __init__(self, bot: Rocketbot):
+		super().__init__(
+			bot,
+			config_prefix='patterns',
+			short_description='Manages message pattern matching.',
+			long_description=_long_help
+		)
+		PatternCog.shared = self
+
+	def get_patterns(self, guild: Guild) -> dict[str, PatternStatement]:
 		"""
 		Returns a name -> PatternStatement lookup for the guild.
 		"""
@@ -80,7 +176,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			Storage.set_state_value(guild, 'PatternCog.last_matched', last_matched)
 		last_matched[name] = time
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_message(self, message: Message) -> None:
 		"""Event listener"""
 		if message.author is None or \
@@ -94,7 +190,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			# Ignore mods
 			return
 
-		patterns = self.__get_patterns(message.guild)
+		patterns = self.get_patterns(message.guild)
 		for statement in sorted(patterns.values(), key=lambda s : s.priority, reverse=True):
 			other_fields = {
 				'last_matched': self.__get_last_matched(message.guild, statement.name),
@@ -189,93 +285,148 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			did_kick=context.is_kicked,
 			did_ban=context.is_banned))
 
-	@commands.group(
-		brief='Manages message pattern matching',
+	pattern = Group(
+		name='pattern',
+		description='Manages message pattern matching.',
+		guild_only=True,
+		default_permissions=MOD_PERMISSIONS,
+		extras={
+			'long_description': _long_help,
+		},
 	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def pattern(self, context: commands.Context):
-		"""Message pattern matching command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
 
 	@pattern.command(
-		brief='Adds a custom pattern',
-		description='Adds a custom pattern. Patterns use a simplified ' + \
-			'expression language. Full documentation found here: ' + \
-			'https://git.rixafrix.com/ialbert/python-app-rocketbot/src/' + \
-			'branch/main/docs/patterns.md',
-		usage='<pattern_name> <expression...>',
-		ignore_extra=True
+		description='Adds or updates a custom pattern.',
+		extras={
+			'long_description': _long_help,
+		},
+	)
+	@autocomplete(
+		name=pattern_name_autocomplete,
+		# actions=action_autocomplete
 	)
-	async def add(self, context: commands.Context, name: str):
-		"""Command handler"""
-		pattern_str = PatternCompiler.expression_str_from_context(context, name)
+	async def add(
+			self,
+			interaction: Interaction,
+			name: str,
+			actions: str,
+			expression: str
+	) -> None:
+		"""
+		Adds a custom pattern.
+
+		Parameters
+		----------
+		interaction : Interaction
+		name : str
+			a name for the new or existing pattern
+		actions : str
+			actions to take when a message matches
+		expression : str
+			criteria for matching chat messages
+		"""
+		pattern_str = f'{actions} if {expression}'
+		guild = interaction.guild
 		try:
 			statement = PatternCompiler.parse_statement(name, pattern_str)
 			statement.check_deprecations()
-			patterns = self.__get_patterns(context.guild)
+			patterns = self.get_patterns(guild)
 			patterns[name] = statement
-			self.__save_patterns(context.guild, patterns)
-			await context.message.reply(
+			self.__save_patterns(guild, patterns)
+			await interaction.response.send_message(
 				f'{CONFIG["success_emoji"]} Pattern `{name}` added.',
-				mention_author=False)
+				ephemeral=True,
+			)
 		except PatternError as e:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["failure_emoji"]} Error parsing statement. {e}',
-				mention_author=False)
+				ephemeral=True,
+			)
 
 	@pattern.command(
-		brief='Removes a custom pattern',
-		usage='<pattern_name>'
+		description='Removes a custom pattern.',
+		extras={
+			'usage': '<pattern_name>',
+		},
 	)
-	async def remove(self, context: commands.Context, name: str):
-		"""Command handler"""
-		patterns = self.__get_patterns(context.guild)
+	@autocomplete(name=pattern_name_autocomplete)
+	async def remove(self, interaction: Interaction, name: str):
+		"""
+		Removes a custom pattern.
+
+		Parameters
+		----------
+		interaction: Interaction
+		name: str
+			name of the pattern to remove
+		"""
+		guild = interaction.guild
+		patterns = self.get_patterns(guild)
 		if patterns.get(name) is not None:
 			del patterns[name]
-			self.__save_patterns(context.guild, patterns)
-			await context.message.reply(
+			self.__save_patterns(guild, patterns)
+			await interaction.response.send_message(
 				f'{CONFIG["success_emoji"]} Pattern `{name}` deleted.',
-				mention_author=False)
+				ephemeral=True,
+			)
 		else:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["failure_emoji"]} No pattern named `{name}`.',
-				mention_author=False)
+				ephemeral=True,
+			)
 
 	@pattern.command(
-		brief='Lists all patterns'
+		description='Lists all patterns.',
 	)
-	async def list(self, context: commands.Context) -> None:
-		"""Command handler"""
-		patterns = self.__get_patterns(context.guild)
+	async def list(self, interaction: Interaction) -> None:
+		guild = interaction.guild
+		patterns = self.get_patterns(guild)
 		if len(patterns) == 0:
-			await context.message.reply('No patterns defined.', mention_author=False)
+			await interaction.response.send_message(
+				'No patterns defined.',
+				ephemeral=True,
+			)
 			return
 		msg = ''
 		for name, statement in sorted(patterns.items()):
 			msg += f'Pattern `{name}` (priority={statement.priority}):\n```\n{statement.original}\n```\n'
-		await context.message.reply(msg, mention_author=False)
+		await interaction.response.send_message(msg, ephemeral=True)
 
 	@pattern.command(
-		brief='Sets a pattern\'s priority level',
-		description='Sets the priority for a pattern. Messages are checked ' +
-			'against patterns with the highest priority first. Patterns with ' +
-			'the same priority may be checked in arbitrary order. Default ' +
+		description="Sets a pattern's priority level.",
+		extras={
+			'long_description': 'Messages are checked against patterns with the '
+								'highest priority first. Patterns with the same '
+								'priority may be checked in arbitrary order. Default '
 								'priority is 100.',
+		},
 	)
-	async def setpriority(self, context: commands.Context, name: str, priority: int) -> None:
-		"""Command handler"""
-		patterns = self.__get_patterns(context.guild)
+	@autocomplete(name=pattern_name_autocomplete, priority=priority_autocomplete)
+	async def setpriority(self, interaction: Interaction, name: str, priority: int) -> None:
+		"""
+		Sets a pattern's priority level.
+
+		Parameters
+		----------
+		interaction: Interaction
+		name: str
+			the name of the pattern
+		priority: int
+			evaluation priority
+		"""
+		guild = interaction.guild
+		patterns = self.get_patterns(guild)
 		statement = patterns.get(name)
 		if statement is None:
-			await context.message.reply(
+			await interaction.response.send_message(
 				f'{CONFIG["failure_emoji"]} No such pattern `{name}`',
-				mention_author=False)
+				ephemeral=True,
+			)
 			return
 		statement.priority = priority
-		self.__save_patterns(context.guild, patterns)
-		await context.message.reply(
+		self.__save_patterns(guild, patterns)
+		await interaction.response.send_message(
 			f'{CONFIG["success_emoji"]} Priority for pattern `{name}` ' + \
 				f'updated to `{priority}`.',
-			mention_author=False)
+			ephemeral=True,
+		)

rocketbot/cogs/urlspamcog.py

@@ -3,8 +3,10 @@ Cog for detecting URLs posted by new users.
 """
 import re
 from datetime import timedelta
+from typing import Literal
+
 from discord import Member, Message, utils as discordutils
-from discord.ext import commands
+from discord.ext.commands import Cog
 from discord.utils import escape_markdown
 
 from config import CONFIG
@@ -27,48 +29,57 @@ class URLSpamCog(BaseCog, name='URL Spam'):
 	Can be configured to take immediate action or just warn the mods.
 	"""
 
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='URL spam detection',
-			description='Whether URLs posted soon after joining are flagged.')
-	SETTING_ACTION = CogSetting('action', str,
+		description='Whether URLs posted soon after joining are flagged.',
+	)
+	SETTING_ACTION = CogSetting(
+		'action',
+		Literal['nothing', 'modwarn', 'delete', 'kick', 'ban'],
+		default_value='nothing',
 		brief='action to take on spam',
 		description='The action to take on detected URL spam.',
-			enum_values={'nothing', 'modwarn', 'delete', 'kick', 'ban'})
-	SETTING_JOIN_AGE = CogSetting('joinage', float,
+		enum_values={'nothing', 'modwarn', 'delete', 'kick', 'ban'},
+	)
+	SETTING_JOIN_AGE = CogSetting(
+		'joinage',
+		timedelta,
+		default_value=timedelta(minutes=15),
 		brief='seconds since member joined',
-			description='The minimum seconds since the user joined the ' + \
-				'server before they can post URLs. URLs posted by users ' + \
-				'who joined too recently will be flagged. Keep in mind ' + \
-				'many servers have a minimum 10 minute cooldown before ' + \
-				'new members can say anything. Setting to 0 effectively ' + \
+		description='The minimum seconds since the user joined the '
+					'server before they can post URLs. URLs posted by users '
+				    'who joined too recently will be flagged. Keep in mind '
+				    'many servers have a minimum 10 minute cooldown before '
+				    'new members can say anything. Setting to 0 effectively '
 				    'disables URL spam detection.',
-			usage='<seconds:int>',
-			min_value=0)
-	SETTING_DECEPTIVE_ACTION = CogSetting('deceptiveaction', str,
+		min_value=timedelta(seconds=0),
+	)
+	SETTING_DECEPTIVE_ACTION = CogSetting(
+		'deceptiveaction',
+		Literal['nothing', 'modwarn', 'modwarndelete', 'chatwarn', 'chatwarndelete', 'delete', 'kick', 'ban'],
+		default_value='nothing',
 		brief='action to take on deceptive link markdown',
-			description='The action to take on chat messages with links ' + \
+		description='The action to take on chat messages with links '
 					'where the text looks like a different URL than the actual link.',
 		enum_values={'nothing', 'modwarn', 'modwarndelete',
-				'chatwarn', 'chatwarndelete', 'delete', 'kick', 'ban'})
+					 'chatwarn', 'chatwarndelete', 'delete', 'kick', 'ban'},
+	)
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='urlspam',
+			short_description='Manages URL spam detection.',
+		)
 		self.add_setting(URLSpamCog.SETTING_ENABLED)
 		self.add_setting(URLSpamCog.SETTING_ACTION)
 		self.add_setting(URLSpamCog.SETTING_JOIN_AGE)
 		self.add_setting(URLSpamCog.SETTING_DECEPTIVE_ACTION)
 
-	@commands.group(
-		brief='Manages URL spam detection',
-	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def urlspam(self, context: commands.Context):
-		"""URL spam command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
-
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_message(self, message: Message):
 		"""Event listener"""
 		if message.author is None or \
@@ -226,7 +237,7 @@ class URLSpamCog(BaseCog, name='URL Spam'):
 					return True
 		return False
 
-	def is_url(self, s: str):
+	def is_url(self, s: str) -> bool:
 		"""Tests if a string is strictly a URL"""
 		ipv6_host_pattern = r'\[[0-9a-fA-F:]+\]'
 		ipv4_host_pattern = r'[0-9\.]+'
@@ -237,7 +248,7 @@ class URLSpamCog(BaseCog, name='URL Spam'):
 		pattern = r'^http[s]?://' + host_pattern + port_pattern + path_pattern + '$'
 		return re.match(pattern, s, re.IGNORECASE) is not None
 
-	def is_casual_url(self, s: str):
+	def is_casual_url(self, s: str) -> bool:
 		"""Tests if a string is a "casual URL" with no scheme included"""
 		ipv6_host_pattern = r'\[[0-9a-fA-F:]+\]'
 		ipv4_host_pattern = r'[0-9\.]+'

rocketbot/cogs/usernamecog.py

@@ -3,12 +3,15 @@ Cog for detecting username patterns.
 """
 from typing import Optional
 
-from discord import Guild, Member
-from discord.ext import commands
+from discord import Guild, Member, Permissions, Interaction
+from discord.app_commands import Group
+from discord.ext.commands import Cog
 
 from config import CONFIG
 from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from rocketbot.storage import Storage
+from rocketbot.utils import MOD_PERMISSIONS
+
 
 class UsernamePatternContext:
 	"""
@@ -44,14 +47,24 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 	message on a match.
 	"""
 
-	SETTING_ENABLED = CogSetting('enabled', bool,
+	SETTING_ENABLED = CogSetting(
+		'enabled',
+		bool,
+		default_value=False,
 		brief='username pattern detection',
-			description='Whether new users are checked for common patterns.')
+		description='Whether new users are checked for username patterns.',
+	)
 
-	SETTING_PATTERNS = CogSetting('patterns', None)
+	SETTING_PATTERNS = CogSetting('patterns', None, default_value=None)
 
 	def __init__(self, bot):
-		super().__init__(bot)
+		super().__init__(
+			bot,
+			config_prefix='username',
+			short_description='Manages username pattern detection.',
+			long_description='When new users join, if their username matches '
+							 'a configured pattern the mods will be alerted.'
+		)
 		self.add_setting(UsernamePatternCog.SETTING_ENABLED)
 
 	def __get_patterns(self, guild: Guild) -> list[str]:
@@ -73,64 +86,104 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 		"""
 		cls.set_guild_setting(guild, cls.SETTING_PATTERNS, patterns)
 
-	@commands.group(
-		brief='Manages username pattern detection'
+	username = Group(
+		name='username',
+		description='Manages username pattern detection.',
+		guild_only=True,
+		default_permissions=MOD_PERMISSIONS,
+		extras={
+			'long_description': 'When new users join, if their username matches '
+								'a configured pattern the mods will be alerted.',
+		},
 	)
-	@commands.has_permissions(ban_members=True)
-	@commands.guild_only()
-	async def username(self, context: commands.Context):
-		"""Username pattern command group"""
-		if context.invoked_subcommand is None:
-			await context.send_help()
 
 	@username.command(
-		brief='Adds a username pattern',
 		description='Adds a username pattern.',
-		usage='<pattern>'
+		extras={
+			'long_description': 'When a user joins the server, if their username '
+								'matches a configured pattern the mods will be alerted. '
+								'Matching is currently a simple substring test.',
+			'usage': '<pattern>',
+		},
 	)
-	async def add(self, context: commands.Context, pattern: str) -> None:
-		"""Command handler"""
+	async def add(self, interaction: Interaction, pattern: str) -> None:
+		"""
+		Adds a username pattern to match against new members.
+
+		Parameters
+		----------
+		interaction : Interaction
+		pattern : str
+			a substring to look for in usernames
+		"""
 		norm_pattern = pattern.lower()
-		patterns: list[str] = self.__get_patterns(context.guild)
+		patterns: list[str] = self.__get_patterns(interaction.guild)
 		if norm_pattern in patterns:
-			await context.reply(f'Pattern `{norm_pattern}` already added.', mention_author=False)
+			await interaction.response.send_message(
+				f'{CONFIG["warning_emoji"]} Pattern `{norm_pattern}` already added.',
+				ephemeral=True
+			)
 			return
 		patterns.append(norm_pattern)
-		self.__save_patterns(context.guild, patterns)
-		await context.reply(f'Pattern `{norm_pattern}` added.', mention_author=False)
+		self.__save_patterns(interaction.guild, patterns)
+		await interaction.response.send_message(
+			f'{CONFIG["success_emoji"]} Pattern `{norm_pattern}` added.',
+			ephemeral=True
+		)
 
 	@username.command(
-		brief='Removes a username pattern',
-		description='Removes an existing username pattern',
-		usage='<pattern>'
+		description='Removes a username pattern.',
+		extras={
+			'usage': '<pattern>',
+		},
 	)
-	async def remove(self, context: commands.Context, pattern: str) -> None:
-		"""Command handler"""
+	async def remove(self, interaction: Interaction, pattern: str) -> None:
+		"""
+		Removes a username pattern.
+
+		Parameters
+		----------
+		interaction : Interaction
+		pattern : str
+		    the existing username pattern to remove
+		"""
 		norm_pattern = pattern.lower()
-		guild: Guild = context.guild
+		guild: Guild = interaction.guild
 		patterns: list[str] = self.__get_patterns(guild)
 		len_before = len(patterns)
 		patterns = list(filter(lambda p: p != norm_pattern, patterns))
 		if len(patterns) == len_before:
-			await context.reply(f'Pattern `{norm_pattern}` not found.', mention_author=False)
+			await interaction.response.send_message(
+				f'{CONFIG["warning_emoji"]} Pattern `{norm_pattern}` not found.',
+				ephemeral=True,
+			)
 			return
 		self.__save_patterns(guild, patterns)
-		await context.reply(f'Pattern `{norm_pattern}` removed.', mention_author=False)
+		await interaction.response.send_message(
+			f'{CONFIG["success_emoji"]} Pattern `{norm_pattern}` removed.',
+			ephemeral=True,
+		)
 
 	@username.command(
-		brief='Lists username patterns'
+		description='Lists existing username patterns.'
 	)
-	async def list(self, context: commands.Context) -> None:
+	async def list(self, interaction: Interaction) -> None:
 		"""Command handler"""
-		guild: Guild = context.guild
+		guild: Guild = interaction.guild
 		patterns: list[str] = self.__get_patterns(guild)
 		if len(patterns) == 0:
-			await context.reply('No patterns defined', mention_author=False)
+			await interaction.response.send_message(
+				f'{CONFIG["success_emoji"]} No patterns defined.',
+				ephemeral=True,
+			)
 		else:
-			msg = 'Patterns:\n\n> `' + '`\n> `'.join(patterns) + '`'
-			await context.reply(msg, mention_author=False)
+			msg = f'{CONFIG["info_emoji"]} Patterns:\n\n> `' + '`\n> `'.join(patterns) + '`'
+			await interaction.response.send_message(
+				msg,
+				ephemeral=True,
+			)
 
-	@commands.Cog.listener()
+	@Cog.listener()
 	async def on_member_join(self, member: Member) -> None:
 		"""Event handler"""
 		for pattern in self.__get_patterns(member.guild):

rocketbot/cogsetting.py

@@ -1,78 +1,98 @@
 """
 A guild configuration setting available for editing via bot commands.
 """
-from typing import Any, Callable, Coroutine, Optional, Type
+from datetime import timedelta
+from typing import Any, Optional, Type, Literal, Union
 
-from discord.ext import commands
-from discord.ext.commands import Bot, Command, Context, Group, Cog
+from discord import Interaction, Permissions
+from discord.app_commands import Range, Transform, describe
+from discord.app_commands.commands import Command, Group, CommandCallback, rename
+from discord.ext.commands import Bot
 
 from config import CONFIG
 from rocketbot.storage import Storage
-from rocketbot.utils import first_command_group
+from rocketbot.utils import bot_log, TimeDeltaTransformer, MOD_PERMISSIONS, dump_stacktrace, str_from_timedelta
 
-def _fix_command(command: Command) -> None:
-	"""
-	HACK: Fixes bug in discord.py 2.3.2 where it's requiring the user to
-	supply the context argument. This removes that argument from the list.
-	"""
-	params = command.params
-	del params['context']
-	command.params = params
+
+def describe_type(datatype: Type) -> str:
+	if datatype is int:
+		return 'integer'
+	if datatype is float:
+		return 'float'
+	if datatype is str:
+		return 'string'
+	if datatype is bool:
+		return 'boolean'
+	if datatype is timedelta:
+		return 'timespan'
+	if getattr(datatype, '__origin__', None) is Union:
+		return '|'.join([ describe_type(a) for a in datatype.__args__ ])
+	if getattr(datatype, '__origin__', None) is Literal:
+		return '"' + ('"|"'.join(datatype.__args__)) + '"'
+	return datatype.__class__.__name__
 
 class CogSetting:
 	"""
 	Describes a configuration setting for a guild that can be edited by the
-	mods of those guilds. BaseCog can generate "get" and "set" commands (or
-	"enable" and "disable" commands for boolean values) automatically, reducing
+	mods of those guilds. BaseCog can generate "/get" and "/set" commands (or
+	"/enable" and "/disable" commands for boolean values) automatically, reducing
 	the boilerplate of generating commands manually. Offers simple validation rules.
 	"""
+
+	permissions: Permissions = Permissions(Permissions.manage_messages.flag)
+
 	def __init__(self,
 			name: str,
 			datatype: Optional[Type],
+			default_value: Any,
 			brief: Optional[str] = None,
 			description: Optional[str] = None,
-			usage: Optional[str] = None,
 			min_value: Optional[Any] = None,
 			max_value: Optional[Any] = None,
 			enum_values: Optional[set[Any]] = None):
 		"""
-		Params:
-		- name         Setting identifier. Must follow variable naming
-		               conventions.
-		- datatype     Datatype of the setting. E.g. int, float, str
-		- brief        Description of the setting, starting with lower case.
+		Parameters
+		----------
+		name: str
+			Setting identifier. Must follow variable naming conventions.
+		datatype: Optional[Type]
+		    Datatype of the setting. E.g. int, float, str
+		default_value: Any
+			Value to use if a guild has not yet configured one.
+		brief: Optional[str]
+			Description of the setting, starting with lower case.
 			Will be inserted into phrases like "Sets <brief>" and
-					   "Gets <brief".
-		- description  Long-form description. Min, max, and enum values will be
+			"Gets <brief>".
+		description: Optional[str]
+		  	Long-form description. Min, max, and enum values will be
 		    appended to the end, so does not need to include these.
-		- usage        Description of the value argument in a set command, e.g.
-		               "<maxcount:int>"
-		- min_value    Smallest allowable value. Must be of the same datatype as
+		min_value: Optional[Any]
+		    Smallest allowable value. Must be of the same datatype as
 		    the value. None for no minimum.
-		- max_value    Largest allowable value. None for no maximum.
-		- enum_values  Set of allowed values. None if unconstrained.
+		max_value: Optional[Any]
+		    Largest allowable value. None for no maximum.
+		enum_values: Optional[set[Any]]
+		  	Set of allowed values. None if unconstrained.
 		"""
 		self.name: str = name
 		self.datatype: Type = datatype
+		self.default_value = default_value
 		self.brief: Optional[str] = brief
 		self.description: str = description or ''  # Can't be None
-		self.usage: Optional[str] = usage
 		self.min_value: Optional[Any] = min_value
 		self.max_value: Optional[Any] = max_value
 		self.enum_values: Optional[set[Any]] = enum_values
-		if self.enum_values or self.min_value is not None or self.max_value is not None:
-			self.description += '\n'
 		if self.enum_values:
-			allowed_values = '`' + ('`, `'.join(enum_values)) + '`'
-			self.description += f'\nAllowed values: {allowed_values}'
-		if self.min_value is not None:
-			self.description += f'\nMin value: {self.min_value}'
-		if self.max_value is not None:
-			self.description += f'\nMax value: {self.max_value}'
-		if self.usage is None:
-			self.usage = f'<{self.name}>'
-
-	def validate_value(self, new_value) -> None:
+			value_list = '`' + ('`, `'.join(self.enum_values)) + '`'
+			self.description += f' (Permitted values: {value_list})'
+		elif self.min_value is not None and self.max_value is not None:
+			self.description += f' (Value must be between `{self.min_value}` and `{self.max_value}`)'
+		elif self.min_value is not None:
+			self.description += f' (Minimum value: {self.min_value})'
+		elif self.max_value is not None:
+			self.description += f' (Maximum value: {self.max_value})'
+
+	def validate_value(self, new_value: Any) -> None:
 		"""
 		Checks if a value is legal for this setting. Raises a ValueError if not.
 		"""
@@ -84,161 +104,327 @@ class CogSetting:
 			allowed_values = '`' + ('`, `'.join(self.enum_values)) + '`'
 			raise ValueError(f'`{self.name}` must be one of {allowed_values}')
 
-	def set_up(self, cog: Cog, bot: Bot, group: Group) -> None:
+	def set_up(self, cog: 'BaseCog') -> None:
 		"""
 		Sets up getter and setter commands for this setting. This should
 		usually only be called by BaseCog.
 		"""
 		if self.name in ('enabled', 'is_enabled'):
-			(group or bot).add_command(self.__make_enable_command(cog))
-			(group or bot).add_command(self.__make_disable_command(cog))
+			self.__enable_group.add_command(self.__make_enable_command(cog))
+			self.__disable_group.add_command(self.__make_disable_command(cog))
 		else:
-			(group or bot).add_command(self.__make_getter_command(cog))
-			(group or bot).add_command(self.__make_setter_command(cog))
+			self.__get_group.add_command(self.__make_getter_command(cog))
+			self.__set_group.add_command(self.__make_setter_command(cog))
+
+	def to_stored_value(self, native_value: Any) -> Any:
+		"""Converts a configuration value to a JSON-compatible datatype."""
+		if self.datatype is timedelta:
+			return native_value.total_seconds()
+		return native_value
+
+	def to_native_value(self, stored_value: Any) -> Any:
+		"""Converts the stored JSON-compatible datatype to its actual value."""
+		if self.datatype is timedelta and isinstance(stored_value, (int, float)):
+			return timedelta(seconds=stored_value)
+		return stored_value
 
-	def __make_getter_command(self, cog: Cog) -> Command:
+	@staticmethod
+	def native_value_to_str(native_value: Any) -> str:
+		"""Formats a native configuration value to a user-presentable string."""
+		if native_value is None:
+			return '<no value>'
+		if isinstance(native_value, timedelta):
+			return str_from_timedelta(native_value)
+		if isinstance(native_value, bool):
+			return 'true' if native_value else 'false'
+		return f'{native_value}'
+
+	def __make_getter_command(self, cog: 'BaseCog') -> Command:
 		setting: CogSetting = self
-		async def getter(cog0: Cog, context: Context) -> None:
 		setting_name = setting.name
-			if isinstance(context.command.parent, Group):
-				setting_name = f'{context.command.parent.name}.{setting_name}'
-			key = f'{cog0.__class__.__name__}.{setting.name}'
-			value = Storage.get_config_value(context.guild, key)
+		if cog.config_prefix is not None:
+			setting_name = f'{cog.config_prefix}_{setting_name}'
+		async def getter(interaction: Interaction) -> None:
+			key = f'{cog.__class__.__name__}.{setting.name}'
+			value = setting.to_native_value(Storage.get_config_value(interaction.guild, key))
 			if value is None:
-				value = cog0.get_cog_default(setting.name)
-				await context.message.reply(
-					f'{CONFIG["info_emoji"]} `{setting_name}` is using default of `{value}`',
-					mention_author=False)
+				value = setting.to_native_value(cog.get_cog_default(setting.name))
+				await interaction.response.send_message(
+					f'{CONFIG["info_emoji"]} `{setting_name}` is using default of `{CogSetting.native_value_to_str(value)}`',
+					ephemeral=True
+				)
 			else:
-				await context.message.reply(
-					f'{CONFIG["info_emoji"]} `{setting_name}` is set to `{value}`',
-					mention_author=False)
+				await interaction.response.send_message(
+					f'{CONFIG["info_emoji"]} `{setting_name}` is set to `{CogSetting.native_value_to_str(value)}`',
+					ephemeral=True
+				)
+
+		bot_log(None, cog.__class__, f"Creating command: /get {setting_name}")
 		command = Command(
-			getter,
-			name=f'get{setting.name}',
-			brief=f'Shows {setting.brief}',
-			description=setting.description,
-			checks=[
-				commands.has_permissions(ban_members=True),
-				commands.guild_only(),
-			])
-		command.cog = cog
-		_fix_command(command)
+			name=setting_name,
+			description=f'Shows {self.brief}.',
+			callback=getter,
+			parent=CogSetting.__get_group,
+			extras={
+				'cog': cog,
+				'setting': setting,
+				'long_description': setting.description,
+			},
+		)
 		return command
 
-	def __make_setter_command(self, cog: Cog) -> Command:
+	def __make_setter_command(self, cog: 'BaseCog') -> Command:
 		setting: CogSetting = self
-		async def setter_common(cog0: Cog, context: Context, new_value) -> None:
+		setting_name = setting.name
+		if cog.config_prefix is not None:
+			setting_name = f'{cog.config_prefix}_{setting_name}'
+		async def setter_general(interaction: Interaction, new_value) -> None:
 			try:
 				setting.validate_value(new_value)
 			except ValueError as ve:
-				await context.message.reply(
+				await interaction.response.send_message(
 					f'{CONFIG["failure_emoji"]} {ve}',
-					mention_author=False)
+					ephemeral=True
+				)
 				return
-			setting_name = setting.name
-			if isinstance(context.command.parent, Group):
-				setting_name = f'{context.command.parent.name}.{setting_name}'
-			key = f'{cog0.__class__.__name__}.{setting.name}'
-			Storage.set_config_value(context.guild, key, new_value)
-			await context.message.reply(
-				f'{CONFIG["success_emoji"]} `{setting_name}` is now set to `{new_value}`',
-				mention_author=False)
-			await cog0.on_setting_updated(context.guild, setting)
-			cog0.log(context.guild, f'{context.author.name} set {key} to {new_value}')
-
-		async def setter_int(cog1, context, new_value: int):
-			await setter_common(cog1, context, new_value)
-		async def setter_float(cog2, context, new_value: float):
-			await setter_common(cog2, context, new_value)
-		async def setter_str(cog3, context, new_value: str):
-			await setter_common(cog3, context, new_value)
-		async def setter_bool(cog4, context, new_value: bool):
-			await setter_common(cog4, context, new_value)
-
-		setter: Callable[[Cog, Context, Any], Coroutine]
-		if setting.datatype == int:
+			key = f'{cog.__class__.__name__}.{setting.name}'
+			Storage.set_config_value(interaction.guild, key, setting.to_stored_value(new_value))
+			await interaction.response.send_message(
+				f'{CONFIG["success_emoji"]} `{setting_name}` is now set to `{setting.to_native_value(new_value)}`',
+				ephemeral=True
+			)
+			await cog.on_setting_updated(interaction.guild, setting)
+			cog.log(interaction.guild, f'{interaction.user.name} set {key} to {new_value}')
+
+		setter: CommandCallback = setter_general
+		if self.datatype is int:
+			if self.min_value is not None or self.max_value is not None:
+				r_min = self.min_value
+				r_max = self.max_value
+				@rename(new_value=self.name)
+				@describe(new_value=self.brief)
+				async def setter_range(interaction: Interaction, new_value: Range[int, r_min, r_max]) -> None:
+					await setter_general(interaction, new_value)
+				setter = setter_range
+			else:
+				@rename(new_value=self.name)
+				@describe(new_value=self.brief)
+				async def setter_int(interaction: Interaction, new_value: int) -> None:
+					await setter_general(interaction, new_value)
 				setter = setter_int
-		elif setting.datatype == float:
+		elif self.datatype is float:
+			@rename(new_value=self.name)
+			@describe(new_value=self.brief)
+			async def setter_float(interaction: Interaction, new_value: float) -> None:
+				await setter_general(interaction, new_value)
 			setter = setter_float
-		elif setting.datatype == str:
+		elif self.datatype is timedelta:
+			@rename(new_value=self.name)
+			@describe(new_value=f'{self.brief} (e.g. 30s, 5m, 1h30s, 7d)')
+			async def setter_timedelta(interaction: Interaction, new_value: Transform[timedelta, TimeDeltaTransformer]) -> None:
+				await setter_general(interaction, new_value)
+			setter = setter_timedelta
+		elif getattr(self.datatype, '__origin__', None) == Literal:
+			dt = self.datatype
+			@rename(new_value=self.name)
+			@describe(new_value=self.brief)
+			async def setter_enum(interaction: Interaction, new_value: dt) -> None:
+				await setter_general(interaction, new_value)
+			setter = setter_enum
+		elif self.datatype is str:
+			if self.enum_values is not None:
+				raise ValueError('Type for a setting with enum values should be typing.Literal')
+			else:
+				@rename(new_value=self.name)
+				@describe(new_value=self.brief)
+				async def setter_str(interaction: Interaction, new_value: str) -> None:
+					await setter_general(interaction, new_value)
 				setter = setter_str
-		elif setting.datatype == bool:
+		elif self.datatype is bool:
+			@rename(new_value=self.name)
+			@describe(new_value=self.brief)
+			async def setter_bool(interaction: Interaction, new_value: bool) -> None:
+				await setter_general(interaction, new_value)
 			setter = setter_bool
-		else:
-			raise ValueError(f'Datatype {setting.datatype} unsupported')
+		elif self.datatype is not None:
+			raise ValueError(f'Invalid type {self.datatype}')
 
+		bot_log(None, cog.__class__, f"Creating command: /set {setting_name} <{describe_type(self.datatype)}>")
 		command = Command(
-			setter,
-			name=f'set{setting.name}',
-			brief=f'Sets {setting.brief}',
-			description=setting.description,
-			usage=setting.usage,
-			checks=[
-				commands.has_permissions(ban_members=True),
-				commands.guild_only(),
-			])
-		# HACK: Passing `cog` in init gets ignored and set to `None` so set after.
-		# This ensures the callback is passed the cog as `self` argument.
-		command.cog = cog
-		_fix_command(command)
+			name=setting_name,
+			description=f'Sets {self.brief}.',
+			callback=setter,
+			parent=CogSetting.__set_group,
+			extras={
+				'cog': cog,
+				'setting': setting,
+				'long_description': setting.description,
+			},
+		)
 		return command
 
-	def __make_enable_command(self, cog: Cog) -> Command:
+	def __make_enable_command(self, cog: 'BaseCog') -> Command:
 		setting: CogSetting = self
-		async def enabler(cog0: Cog, context: Context) -> None:
-			key = f'{cog0.__class__.__name__}.{setting.name}'
-			Storage.set_config_value(context.guild, key, True)
-			await context.message.reply(
+		async def enabler(interaction: Interaction) -> None:
+			key = f'{cog.__class__.__name__}.{setting.name}'
+			Storage.set_config_value(interaction.guild, key, True)
+			await interaction.response.send_message(
 				f'{CONFIG["success_emoji"]} {setting.brief.capitalize()} enabled.',
-				mention_author=False)
-			await cog0.on_setting_updated(context.guild, setting)
-			cog0.log(context.guild, f'{context.author.name} enabled {cog0.__class__.__name__}')
+				ephemeral=True
+			)
+			await cog.on_setting_updated(interaction.guild, setting)
+			cog.log(interaction.guild, f'{interaction.user.name} enabled {cog.__class__.__name__}')
 
+		bot_log(None, cog.__class__, f"Creating command: /enable {cog.config_prefix}")
 		command = Command(
-			enabler,
-			name='enable',
-			brief=f'Enables {setting.brief}',
-			description=setting.description,
-			checks=[
-				commands.has_permissions(ban_members=True),
-				commands.guild_only(),
-			])
-		command.cog = cog
-		_fix_command(command)
+			name=cog.config_prefix,
+			description=f'Enables {cog.qualified_name} functionality.',
+			callback=enabler,
+			parent=CogSetting.__enable_group,
+			extras={
+				'cog': cog,
+				'setting': setting,
+				'long_description': setting.description,
+			},
+		)
 		return command
 
-	def __make_disable_command(self, cog: Cog) -> Command:
+	def __make_disable_command(self, cog: 'BaseCog') -> Command:
 		setting: CogSetting = self
-		async def disabler(cog0: Cog, context: Context) -> None:
-			key = f'{cog0.__class__.__name__}.{setting.name}'
-			Storage.set_config_value(context.guild, key, False)
-			await context.message.reply(
+		async def disabler(interaction: Interaction) -> None:
+			key = f'{cog.__class__.__name__}.{setting.name}'
+			Storage.set_config_value(interaction.guild, key, False)
+			await interaction.response.send_message(
 				f'{CONFIG["success_emoji"]} {setting.brief.capitalize()} disabled.',
-				mention_author=False)
-			await cog0.on_setting_updated(context.guild, setting)
-			cog0.log(context.guild, f'{context.author.name} disabled {cog0.__class__.__name__}')
+				ephemeral=True
+			)
+			await cog.on_setting_updated(interaction.guild, setting)
+			cog.log(interaction.guild, f'{interaction.user.name} disabled {cog.__class__.__name__}')
 
+		bot_log(None, cog.__class__, f"Creating command: /disable {cog.config_prefix}")
 		command = Command(
-			disabler,
-			name='disable',
-			brief=f'Disables {setting.brief}',
-			description=setting.description,
-			checks=[
-				commands.has_permissions(ban_members=True),
-				commands.guild_only(),
-			])
-		command.cog = cog
-		_fix_command(command)
+			name=cog.config_prefix,
+			description=f'Disables {cog.config_prefix} functionality',
+			callback=disabler,
+			parent=CogSetting.__disable_group,
+			extras={
+				'cog': cog,
+				'setting': setting,
+				'long_description': setting.description,
+			},
+		)
 		return command
 
+	__set_group: Group
+	__get_group: Group
+	__enable_group: Group
+	__disable_group: Group
+
 	@classmethod
-	def set_up_all(cls, cog: Cog, bot: Bot, settings: list) -> None:
+	def set_up_all(cls, cog: 'BaseCog', bot: Bot, settings: list['CogSetting']) -> None:
 		"""
 		Sets up editing commands for a list of CogSettings and adds them to a
 		cog. If the cog has a command Group, commands will be added to it.
-		Otherwise they will be added at the top level.
+		Otherwise, they will be added at the top level.
 		"""
-		group: Group = first_command_group(cog)
+		cls.__set_up_base_commands(bot)
+		if len(settings) == 0:
+			return
 		for setting in settings:
-			setting.set_up(cog, bot, group)
+			setting.set_up(cog)
+
+	@classmethod
+	def __set_up_base_commands(cls, bot: Bot) -> None:
+		if getattr(cls, f'_CogSetting__set_group', None) is not None:
+			return
+		cls.__set_group = Group(
+			name='set',
+			description='Sets a configuration value for this guild.',
+			guild_only=True,
+			default_permissions=MOD_PERMISSIONS,
+			extras={
+				'long_description': 'Settings are guild-specific. If no value is set, a default is used. Use `/get` to '
+									'see the current value for this guild.',
+			},
+		)
+		cls.__get_group = Group(
+			name='get',
+			description='Shows a configuration value for this guild.',
+			guild_only=True,
+			default_permissions=MOD_PERMISSIONS,
+			extras={
+				'long_description': 'Settings are guild-specific. If no value is set, a default is used. Use `/set` to '
+									'change the value.',
+			},
+		)
+		cls.__enable_group = Group(
+			name='enable',
+			description='Enables a module for this guild.',
+			guild_only=True,
+			default_permissions=MOD_PERMISSIONS,
+			extras={
+				'long_description': 'Modules are enabled on a per-guild basis and are off by default. Use `/disable` '
+									'to disable an enabled module.',
+			},
+		)
+		cls.__disable_group = Group(
+			name='disable',
+			description='Disables a module for this guild.',
+			guild_only=True,
+			default_permissions=MOD_PERMISSIONS,
+			extras={
+				'long_description': 'Modules are enabled on a per-guild basis and are off by default. Use `/enable` '
+					                're-enable a disabled module.',
+			},
+		)
+		bot.tree.add_command(cls.__set_group)
+		bot.tree.add_command(cls.__get_group)
+		bot.tree.add_command(cls.__enable_group)
+		bot.tree.add_command(cls.__disable_group)
+
+		from rocketbot.cogs.basecog import BaseCog
+		async def show_all(interaction: Interaction) -> None:
+			try:
+				guild = interaction.guild
+				if guild is None:
+					await interaction.response.send_message(
+						f'{CONFIG["failure_emoji"]} No guild.',
+						ephemeral=True,
+						delete_after=10,
+					)
+					return
+				text = '## :information_source: Configuration'
+				for cog_name, cog in sorted(bot.cogs.items()):
+					if not isinstance(cog, BaseCog):
+						continue
+					bcog: BaseCog = cog
+					if len(bcog.settings) == 0:
+						continue
+					text += f'\n### {bcog.qualified_name} Module'
+					for setting in sorted(bcog.settings, key=lambda s: (s.name != 'enabled', s.name)):
+						key = f'{bcog.__class__.__name__}.{setting.name}'
+						value = setting.to_native_value(Storage.get_config_value(guild, key))
+						deflt = setting.to_native_value(bcog.get_cog_default(setting.name))
+						if setting.name == 'enabled':
+							text += f'\n- Module is '
+							if value is not None:
+								text += '**' + ('enabled' if value else 'disabled') + '**'
+							else:
+								text += ('enabled' if deflt else 'disabled') + ' _(default)_'
+						else:
+							if value is not None:
+								text += f'\n- `{bcog.config_prefix}_{setting.name}` = **{CogSetting.native_value_to_str(value)}**'
+							else:
+								text += f'\n- `{bcog.config_prefix}_{setting.name}` = {CogSetting.native_value_to_str(deflt)} _(using default)_'
+				await interaction.response.send_message(
+					text,
+					ephemeral=True,
+				)
+			except BaseException as e:
+				dump_stacktrace(e)
+		show_all_command = Command(
+			name='all',
+			description='Shows all configuration for this guild.',
+			callback=show_all,
+		)
+		cls.__get_group.add_command(show_all_command)

rocketbot/pattern.py

@@ -5,7 +5,7 @@ to take on them.
 import re
 from abc import ABCMeta, abstractmethod
 from datetime import datetime, timezone
-from typing import Any, Union
+from typing import Any, Union, Literal
 
 from discord import Message, utils as discordutils
 from discord.ext.commands import Context
@@ -13,6 +13,11 @@ from discord.ext.commands import Context
 from rocketbot.utils import is_user_id, str_from_quoted_str, timedelta_from_str, \
 	user_id_from_mention
 
+PatternField = Literal['content.markdown', 'content', 'content.plain', 'author', 'author.id', 'author.joinage', 'author.name', 'lastmatched']
+PatternComparisonOperator = Literal['==', '!=', '<', '>', '<=', '>=', 'contains', '!contains', 'matches', '!matches', 'containsword', '!containsword']
+PatternBooleanOperator = Literal['!', 'and', 'or']
+PatternActionType = Literal['ban', 'delete', 'kick', 'modinfo', 'modwarn', 'reply']
+
 class PatternError(RuntimeError):
 	"""
 	Error thrown when parsing a pattern statement.
@@ -27,6 +32,14 @@ class PatternAction:
 	"""
 	Describes one action to take on a matched message or its author.
 	"""
+
+	TYPE_BAN: PatternActionType = 'ban'
+	TYPE_DELETE: PatternActionType = 'delete'
+	TYPE_KICK: PatternActionType = 'kick'
+	TYPE_INFORM_MODS: PatternActionType = 'modinfo'
+	TYPE_WARN_MODS: PatternActionType = 'modwarn'
+	TYPE_REPLY: PatternActionType = 'reply'
+
 	def __init__(self, action: str, args: list[Any]):
 		self.action = action
 		self.arguments = list(args)
@@ -55,56 +68,81 @@ class PatternSimpleExpression(PatternExpression):
 	Message matching expression with a simple "<field> <operator> <value>"
 	structure.
 	"""
-	def __init__(self, field: str, operator: str, value: Any):
+
+	FIELD_CONTENT_MARKDOWN: PatternField = 'content.markdown'
+	FIELD_CONTENT_PLAIN: PatternField = 'content.plain'
+	FIELD_AUTHOR_ID: PatternField = 'author.id'
+	FIELD_AUTHOR_JOINAGE: PatternField = 'author.joinage'
+	FIELD_AUTHOR_NAME: PatternField = 'author.name'
+	FIELD_LAST_MATCHED: PatternField = 'lastmatched'
+
+	# Less preferred but recognized field aliases
+	ALIAS_FIELD_CONTENT_MARKDOWN: PatternField = 'content'
+	ALIAS_FIELD_AUTHOR_ID: PatternField = 'author'
+
+	OP_EQUALS: PatternComparisonOperator = '=='
+	OP_NOT_EQUALS: PatternComparisonOperator = '!='
+	OP_LESS_THAN: PatternComparisonOperator = '<'
+	OP_GREATER_THAN: PatternComparisonOperator = '>'
+	OP_LESS_THAN_OR_EQUALS: PatternComparisonOperator = '<='
+	OP_GREATER_THAN_OR_EQUALS: PatternComparisonOperator = '>='
+	OP_CONTAINS: PatternComparisonOperator = 'contains'
+	OP_NOT_CONTAINS: PatternComparisonOperator = '!contains'
+	OP_MATCHES: PatternComparisonOperator = 'matches'
+	OP_NOT_MATCHES: PatternComparisonOperator = '!matches'
+	OP_CONTAINS_WORD: PatternComparisonOperator = 'containsword'
+	OP_NOT_CONTAINS_WORD: PatternComparisonOperator = '!containsword'
+
+	def __init__(self, field: PatternField, operator: PatternComparisonOperator, value: Any):
 		super().__init__()
-		self.field: str = field
-		self.operator: str = operator
+		self.field: PatternField = field
+		self.operator: PatternComparisonOperator = operator
 		self.value: Any = value
 
 	def __field_value(self, message: Message, other_fields: dict[str, Any]) -> Any:
-		if self.field in ('content.markdown', 'content'):
+		cls = PatternSimpleExpression
+		if self.field in (cls.FIELD_CONTENT_MARKDOWN, cls.ALIAS_FIELD_CONTENT_MARKDOWN):
 			return message.content
-		if self.field == 'content.plain':
+		if self.field == cls.FIELD_CONTENT_PLAIN:
 			return discordutils.remove_markdown(message.clean_content)
-		if self.field == 'author':
+		if self.field in (cls.FIELD_AUTHOR_ID, cls.ALIAS_FIELD_AUTHOR_ID):
 			return str(message.author.id)
-		if self.field == 'author.id':
-			return str(message.author.id)
-		if self.field == 'author.joinage':
+		if self.field == cls.FIELD_AUTHOR_JOINAGE:
 			return message.created_at - message.author.joined_at
-		if self.field == 'author.name':
+		if self.field == cls.FIELD_AUTHOR_NAME:
 			return message.author.name
-		if self.field == 'lastmatched':
+		if self.field == cls.FIELD_LAST_MATCHED:
 			long_ago = datetime(year=1900, month=1, day=1, hour=0, minute=0, second=0, tzinfo=timezone.utc)
 			last_matched = other_fields.get('last_matched') or long_ago
 			return message.created_at - last_matched
-		raise ValueError(f'Bad field name {self.field}')
+		raise ValueError(f'Bad field name "{self.field}"')
 
 	def matches(self, message: Message, other_fields: dict[str, Any]) -> bool:
+		cls = PatternSimpleExpression
 		field_value = self.__field_value(message, other_fields)
-		if self.operator == '==':
+		if self.operator == cls.OP_EQUALS:
 			if isinstance(field_value, str) and isinstance(self.value, str):
 				return field_value.lower() == self.value.lower()
 			return field_value == self.value
-		if self.operator == '!=':
+		if self.operator == cls.OP_NOT_EQUALS:
 			if isinstance(field_value, str) and isinstance(self.value, str):
 				return field_value.lower() != self.value.lower()
 			return field_value != self.value
-		if self.operator == '<':
+		if self.operator == cls.OP_LESS_THAN:
 			return field_value < self.value
-		if self.operator == '>':
+		if self.operator == cls.OP_GREATER_THAN:
 			return field_value > self.value
-		if self.operator == '<=':
+		if self.operator == cls.OP_LESS_THAN_OR_EQUALS:
 			return field_value <= self.value
-		if self.operator == '>=':
+		if self.operator == cls.OP_GREATER_THAN_OR_EQUALS:
 			return field_value >= self.value
-		if self.operator == 'contains':
+		if self.operator == cls.OP_CONTAINS:
 			return self.value.lower() in field_value.lower()
-		if self.operator == '!contains':
+		if self.operator == cls.OP_NOT_CONTAINS:
 			return self.value.lower() not in field_value.lower()
-		if self.operator in ('matches', 'containsword'):
+		if self.operator in (cls.OP_MATCHES, cls.OP_CONTAINS_WORD):
 			return self.value.search(field_value.lower()) is not None
-		if self.operator in ('!matches', '!containsword'):
+		if self.operator in (cls.OP_NOT_MATCHES, cls.OP_NOT_CONTAINS_WORD):
 			return self.value.search(field_value.lower()) is None
 		raise ValueError(f'Bad operator {self.operator}')
 
@@ -116,20 +154,24 @@ class PatternCompoundExpression(PatternExpression):
 	Message matching expression that combines several child expressions with
 	a boolean operator.
 	"""
-	def __init__(self, operator: str, operands: list[PatternExpression]):
+	OP_NOT = '!'
+	OP_AND = 'and'
+	OP_OR = 'or'
+
+	def __init__(self, operator: PatternBooleanOperator, operands: list[PatternExpression]):
 		super().__init__()
-		self.operator = operator
+		self.operator: PatternBooleanOperator = operator
 		self.operands = list(operands)
 
 	def matches(self, message: Message, other_fields: dict[str, Any]) -> bool:
-		if self.operator == '!':
+		if self.operator == PatternCompoundExpression.OP_NOT:
 			return not self.operands[0].matches(message, other_fields)
-		if self.operator == 'and':
+		if self.operator == PatternCompoundExpression.OP_AND:
 			for op in self.operands:
 				if not op.matches(message, other_fields):
 					return False
 			return True
-		if self.operator == 'or':
+		if self.operator == PatternCompoundExpression.OP_OR:
 			for op in self.operands:
 				if op.matches(message, other_fields):
 					return True
@@ -137,7 +179,7 @@ class PatternCompoundExpression(PatternExpression):
 		raise ValueError(f'Bad operator "{self.operator}"')
 
 	def __str__(self) -> str:
-		if self.operator == '!':
+		if self.operator == PatternCompoundExpression.OP_NOT:
 			return f'(!( {self.operands[0]} ))'
 		strs = map(str, self.operands)
 		joined = f' {self.operator} '.join(strs)
@@ -204,52 +246,63 @@ class PatternCompiler:
 	"""
 	Parses a user-provided message filter statement into a PatternStatement.
 	"""
-	TYPE_FLOAT: str = 'float'
-	TYPE_ID: str = 'id'
-	TYPE_INT: str = 'int'
-	TYPE_MEMBER: str = 'Member'
-	TYPE_REGEX: str = 'regex'
-	TYPE_TEXT: str = 'text'
-	TYPE_TIMESPAN: str = 'timespan'
-
-	FIELD_TO_TYPE: dict[str, str] = {
-		'author': TYPE_MEMBER,
-		'author.id': TYPE_ID,
-		'author.joinage': TYPE_TIMESPAN,
-		'author.name': TYPE_TEXT,
-		'content': TYPE_TEXT, # deprecated, use content.markdown or content.plain
-		'content.markdown': TYPE_TEXT,
-		'content.plain': TYPE_TEXT,
-		'lastmatched': TYPE_TIMESPAN,
+	DATATYPE_FLOAT: str = 'float'
+	DATATYPE_ID: str = 'id'
+	DATATYPE_INT: str = 'int'
+	DATATYPE_MEMBER: str = 'Member'
+	DATATYPE_REGEX: str = 'regex'
+	DATATYPE_TEXT: str = 'text'
+	DATATYPE_TIMESPAN: str = 'timespan'
+
+	FIELD_TO_DATATYPE: dict[PatternField, str] = {
+		PatternSimpleExpression.ALIAS_FIELD_AUTHOR_ID: DATATYPE_MEMBER,
+		PatternSimpleExpression.FIELD_AUTHOR_ID: DATATYPE_ID,
+		PatternSimpleExpression.FIELD_AUTHOR_JOINAGE: DATATYPE_TIMESPAN,
+		PatternSimpleExpression.FIELD_AUTHOR_NAME: DATATYPE_TEXT,
+		PatternSimpleExpression.ALIAS_FIELD_CONTENT_MARKDOWN: DATATYPE_TEXT, # deprecated, use content.markdown or content.plain
+		PatternSimpleExpression.FIELD_CONTENT_MARKDOWN: DATATYPE_TEXT,
+		PatternSimpleExpression.FIELD_CONTENT_PLAIN: DATATYPE_TEXT,
+		PatternSimpleExpression.FIELD_LAST_MATCHED: DATATYPE_TIMESPAN,
 	}
-	DEPRECATED_FIELDS: set[str] = { 'content' }
-
-	ACTION_TO_ARGS: dict[str, list[str]] = {
-		'ban': [],
-		'delete': [],
-		'kick': [],
-		'modinfo': [],
-		'modwarn': [],
-		'reply': [ TYPE_TEXT ],
+	DEPRECATED_FIELDS: set[PatternField] = { 'content' }
+
+	ACTION_TO_ARGS: dict[PatternActionType, list[str]] = {
+		PatternAction.TYPE_BAN: [],
+		PatternAction.TYPE_DELETE: [],
+		PatternAction.TYPE_KICK: [],
+		PatternAction.TYPE_INFORM_MODS: [],
+		PatternAction.TYPE_WARN_MODS: [],
+		PatternAction.TYPE_REPLY: [ DATATYPE_TEXT ],
 	}
 
-	OPERATORS_IDENTITY: set[str] = { '==', '!=' }
-	OPERATORS_COMPARISON: set[str] = { '<', '>', '<=', '>=' }
-	OPERATORS_NUMERIC: set[str] = OPERATORS_IDENTITY | OPERATORS_COMPARISON
-	OPERATORS_TEXT: set[str] = OPERATORS_IDENTITY | {
-		'contains', '!contains',
-		'containsword', '!containsword',
-		'matches', '!matches',
+	OPERATORS_IDENTITY: set[PatternComparisonOperator] = {
+		PatternSimpleExpression.OP_EQUALS,
+		PatternSimpleExpression.OP_NOT_EQUALS,
+	}
+	OPERATORS_COMPARISON: set[PatternComparisonOperator] = {
+		PatternSimpleExpression.OP_LESS_THAN,
+		PatternSimpleExpression.OP_GREATER_THAN,
+		PatternSimpleExpression.OP_LESS_THAN_OR_EQUALS,
+		PatternSimpleExpression.OP_GREATER_THAN_OR_EQUALS,
+	}
+	OPERATORS_NUMERIC: set[PatternComparisonOperator] = OPERATORS_IDENTITY | OPERATORS_COMPARISON
+	OPERATORS_TEXT: set[PatternComparisonOperator] = OPERATORS_IDENTITY | {
+		PatternSimpleExpression.OP_CONTAINS,
+		PatternSimpleExpression.OP_NOT_CONTAINS,
+		PatternSimpleExpression.OP_CONTAINS_WORD,
+		PatternSimpleExpression.OP_NOT_CONTAINS_WORD,
+		PatternSimpleExpression.OP_MATCHES,
+		PatternSimpleExpression.OP_NOT_MATCHES,
 	}
 	OPERATORS_ALL: set[str] = OPERATORS_IDENTITY | OPERATORS_COMPARISON | OPERATORS_TEXT
 
-	TYPE_TO_OPERATORS: dict[str, set[str]] = {
-		TYPE_ID: OPERATORS_IDENTITY,
-		TYPE_MEMBER: OPERATORS_IDENTITY,
-		TYPE_TEXT: OPERATORS_TEXT,
-		TYPE_INT: OPERATORS_NUMERIC,
-		TYPE_FLOAT: OPERATORS_NUMERIC,
-		TYPE_TIMESPAN: OPERATORS_NUMERIC,
+	DATATYPE_TO_OPERATORS: dict[str, set[PatternComparisonOperator]] = {
+		DATATYPE_ID: OPERATORS_IDENTITY,
+		DATATYPE_MEMBER: OPERATORS_IDENTITY,
+		DATATYPE_TEXT: OPERATORS_TEXT,
+		DATATYPE_INT: OPERATORS_NUMERIC,
+		DATATYPE_FLOAT: OPERATORS_NUMERIC,
+		DATATYPE_TIMESPAN: OPERATORS_NUMERIC,
 	}
 
 	WHITESPACE_CHARS: str = ' \t\n\r'
@@ -458,7 +511,7 @@ class PatternCompiler:
 					return subexpressions[0], token_index
 				return (PatternCompoundExpression(last_compound_operator,
 					subexpressions), token_index)
-			if tokens[token_index] in { "and", "or" }:
+			if tokens[token_index] in { PatternCompoundExpression.OP_AND, PatternCompoundExpression.OP_OR }:
 				compound_operator = tokens[token_index]
 				if last_compound_operator and \
 						compound_operator != last_compound_operator:
@@ -468,7 +521,7 @@ class PatternCompiler:
 					]
 				last_compound_operator = compound_operator
 				token_index += 1
-			if tokens[token_index] == '!':
+			if tokens[token_index] == PatternCompoundExpression.OP_NOT:
 				(exp, next_index) = cls.__read_expression(tokens,
 						token_index + 1, depth + 1, one_subexpression=True)
 				subexpressions.append(PatternCompoundExpression('!', [exp]))
@@ -507,10 +560,10 @@ class PatternCompiler:
 			raise PatternError('Expression nests too deeply')
 		if token_index >= len(tokens):
 			raise PatternError('Expected field name, found EOL')
-		field = tokens[token_index]
+		field: PatternField = tokens[token_index]
 		token_index += 1
 
-		datatype = cls.FIELD_TO_TYPE.get(field)
+		datatype = cls.FIELD_TO_DATATYPE.get(field, None)
 		if datatype is None:
 			raise PatternError(f'No such field "{field}"')
 
@@ -519,13 +572,13 @@ class PatternCompiler:
 		op = tokens[token_index]
 		token_index += 1
 
-		if op == '!':
+		if op == PatternCompoundExpression.OP_NOT:
 			if token_index >= len(tokens):
 				raise PatternError('Expected operator, found EOL')
 			op = '!' + tokens[token_index]
 			token_index += 1
 
-		allowed_ops = cls.TYPE_TO_OPERATORS[datatype]
+		allowed_ops = cls.DATATYPE_TO_OPERATORS[datatype]
 		if op not in allowed_ops:
 			if op in cls.OPERATORS_ALL:
 				raise PatternError(f'Operator {op} cannot be used with ' + \
@@ -551,13 +604,13 @@ class PatternCompiler:
 		"""
 		Converts a value token to its Python value. Raises ValueError on failure.
 		"""
-		if datatype == cls.TYPE_ID:
+		if datatype == cls.DATATYPE_ID:
 			if not is_user_id(value):
 				raise ValueError(f'Illegal user id value: {value}')
 			return value
-		if datatype == cls.TYPE_MEMBER:
+		if datatype == cls.DATATYPE_MEMBER:
 			return user_id_from_mention(value)
-		if datatype == cls.TYPE_TEXT:
+		if datatype == cls.DATATYPE_TEXT:
 			s = str_from_quoted_str(value)
 			if op in ('matches', '!matches'):
 				try:
@@ -570,10 +623,10 @@ class PatternCompiler:
 				except re.error as e:
 					raise ValueError(f'Invalid regex: {e}') from e
 			return s
-		if datatype == cls.TYPE_INT:
+		if datatype == cls.DATATYPE_INT:
 			return int(value)
-		if datatype == cls.TYPE_FLOAT:
+		if datatype == cls.DATATYPE_FLOAT:
 			return float(value)
-		if datatype == cls.TYPE_TIMESPAN:
+		if datatype == cls.DATATYPE_TIMESPAN:
 			return timedelta_from_str(value)
 		raise ValueError(f'Unhandled datatype {datatype}')

rocketbot/utils.py

@@ -7,25 +7,42 @@ import traceback
 from datetime import datetime, timedelta
 from typing import Any, Optional, Type, Union
 
-from discord import Guild
-from discord.ext.commands import Cog, Group
+import discord
+from discord import Guild, Permissions
+from discord.ext.commands import Cog
 
-def dump_stacktrace(e: Exception) -> None:
+def dump_stacktrace(e: BaseException) -> None:
 	print(e, file=sys.stderr)
 	traceback.print_exception(type(e), e, e.__traceback__)
 
 def timedelta_from_str(s: str) -> timedelta:
 	"""
-	Parses a timespan. Format examples:
+	Parses a timespan.
+
+	Format examples:
 	"30m"
 	"10s"
 	"90d"
 	"1h30m"
 	"73d18h22m52s"
+
+	Parameters
+	----------
+	s : str
+		string to parse
+
+	Returns
+	-------
+	timedelta
+
+	Raises
+	------
+	ValueError
+		if parsing fails
 	"""
-	p: re.Pattern = re.compile('^(?:[0-9]+[dhms])+$')
+	p: re.Pattern = re.compile('^(?:[0-9]+[a-zA-Z])+$')
 	if p.match(s) is None:
-		raise ValueError("Illegal timespan value '{s}'.")
+		raise ValueError(f'Illegal timespan value "{s}". Examples: 30s, 5m, 1h30m, 30d')
 	p = re.compile('([0-9]+)([dhms])')
 	days: int = 0
 	hours: int = 0
@@ -33,7 +50,7 @@ def timedelta_from_str(s: str) -> timedelta:
 	seconds: int = 0
 	for m in p.finditer(s):
 		scalar = int(m.group(1))
-		unit = m.group(2)
+		unit = m.group(2).lower()
 		if unit == 'd':
 			days = scalar
 		elif unit == 'h':
@@ -42,6 +59,8 @@ def timedelta_from_str(s: str) -> timedelta:
 			minutes = scalar
 		elif unit == 's':
 			seconds = scalar
+		else:
+			raise ValueError(f'Invalid unit "{unit}". Valid units: "s"=seconds, "m"=minutes, "h"=hours, "d"=days')
 	return timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
 
 def str_from_timedelta(td: timedelta) -> str:
@@ -84,11 +103,19 @@ def describe_timedelta(td: timedelta, max_components: int = 2) -> str:
 		components = components[0:max_components]
 	return ' '.join(components)
 
-def first_command_group(cog: Cog) -> Optional[Group]:
+def _old_first_command_group(cog: Cog) -> Optional[discord.ext.commands.Group]:
 	"""Returns the first command Group found in a cog."""
 	for member_name in dir(cog):
 		member = getattr(cog, member_name)
-		if isinstance(member, Group):
+		if isinstance(member, discord.ext.commands.Group):
+			return member
+	return None
+
+def first_command_group(cog: Cog) -> Optional[discord.app_commands.Group]:
+	"""Returns the first slash command Group found in a cog."""
+	for member_name in dir(cog):
+		member = getattr(cog, member_name)
+		if isinstance(member, discord.app_commands.Group):
 			return member
 	return None
 
@@ -143,3 +170,21 @@ def str_from_quoted_str(val: str) -> str:
 	if len(val) < 2 or val[0:1] not in __QUOTE_CHARS or val[-1:] not in __QUOTE_CHARS:
 		raise ValueError(f'Not a quoted string: {val}')
 	return val[1:-1]
+
+MOD_PERMISSIONS: Permissions = Permissions(Permissions.manage_messages.flag)
+
+from discord import Interaction
+from discord.app_commands import Transformer
+from discord.ext.commands import BadArgument
+
+class TimeDeltaTransformer(Transformer):
+	async def transform(self, interaction: Interaction, value: Any) -> timedelta:
+		try:
+			return timedelta_from_str(str(value))
+		except ValueError as e:
+			print("Invalid time delta:", e)
+			raise BadArgument(str(e))
+
+	@property
+	def _error_display_name(self) -> str:
+		return 'timedelta'