Utility Commands & Help

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/util/help.ts
• src/commands/util/user-info.ts
• src/commands/util/config.ts
• src/commands/util/rules.ts
• src/commands/util/backend-manager.ts
• src/commands/util/members.ts
• src/commands/util/xp.ts
• src/util/helpers.ts

The Utility module in the Poixpixel Discord Bot provides a suite of administrative and informational tools designed to assist both users and staff members. These commands range from general information retrieval (such as help menus and user statistics) to critical system management tasks (including backend service monitoring and configuration inspection).

This system is built upon the discord.js framework, utilizing Slash Commands for user interaction. The module integrates closely with the bot's database and caching layers to provide real-time status updates and historical data for moderation and system administration.

Help System Architecture

The help system is a dynamic, interactive interface that categorizes commands and provides detailed documentation links. It supports both a general overview through a selection menu and targeted lookups for specific command parameters.

Logic Flow

When a user invokes /help, the bot performs the following steps:

1. Categorization: It iterates through the client's command map and groups commands into predefined categories like fun, moderation, util, and testing.
2. Interactive Menu: It generates an embed with a StringSelectMenuBuilder. Users can select a category to view specific commands within that group.
3. Detailed Lookup: If a command string option is provided, the bot skips the menu and directly displays the specific command's description, subcommands, and options.

The following diagram illustrates the interaction flow of the help command:

Help Command Categories

Emoji	Category	Description
🎮	Fun	Game-related and engagement commands (e.g., counting, fact, rank).
🛡️	Moderation	Staff-only commands for user management (e.g., ban, kick, warn).
🔧	Util	System management and information tools (e.g., config, help, user-info).
🧪	Testing	Development and debug commands (e.g., test-join).

Sources: src/commands/util/help.ts:70-75, src/commands/util/help.ts:167-200

User and Server Information

Utility commands provide deep insights into user history and server structure by querying both the Discord API and the internal database.

User Information (/user-info)

This command aggregates data to provide a comprehensive view of a member's profile. It is restricted to users with ModerateMembers permissions.

• Basic Info: Username, Discord ID, Account creation date, and Server join date.
• Moderation History: Total counts of warnings, mutes, and bans stored in the moderationTable.
• Activity Stats: Counting game mistakes and warnings derived from getCountingData().

Sources: src/commands/util/user-info.ts:14-118

Member Listing (/members)

The /members command retrieves all non-bot members stored in the database. It uses a pagination system to handle large lists, providing:

• Alphabetical Sorting: Members are sorted by username.
• Data Points: Displays the username alongside the Discord Snowflake ID.
• Total Count: Shows the aggregate number of tracked members.

Sources: src/commands/util/members.ts:18-45

System & Backend Management

The Utility module includes sensitive commands for inspecting the bot's state and managing its infrastructure.

Configuration Inspection (/config)

The /config command provides a paginated view of the bot's current config.json settings. For security, sensitive fields such as token, poolingDbConnectionString, and redisConnectionString are redacted with placeholder characters before being displayed.

Backend Manager (/backend-manager)

This tool is used by staff to monitor and recover service connections without restarting the entire bot process.

Subcommand	Description	Action Taken
status	Checks service health.	Validates ensureDbInitialized() and isRedisConnected().
database	Forced reconnection.	Triggers initializeDatabaseConnection().
redis	Forced reconnection.	Triggers ensureRedisConnection().
flush	Cache clearing.	Triggers flushRedisCache() (Administrator only).

Sources: src/commands/util/backend-manager.ts:40-142

Experience (XP) Management

The /xp command suite allows administrators to manually manipulate user leveling data. These commands interact directly with the database layer via functions like addXpToUser and setXpForUser.

• Add/Remove: Adjusts a user's current XP total.
• Set: Overwrites the current XP with a specific integer value.
• Reset: Safely returns a user's XP to 0.

Before execution, these commands utilize validateInteraction() to ensure the command context (guild and channel) remains valid throughout the asynchronous database operations.
Sources: src/commands/util/xp.ts:14-118

Supporting Utilities

The functionality of these commands is underpinned by several helper functions located in src/util/helpers.ts:

• validateInteraction: Checks if an interaction is still valid in the guild and if the associated message (for components) exists. Line 437-453
• createPaginationButtons: Standardizes the UI for multi-page embeds, providing First, Previous, Next, and Last buttons. Line 482-506
• safeRemoveComponents: Cleans up interactive elements (buttons/menus) after a command times out or finishes to prevent "Interaction Failed" errors for users. Line 552-581

Conclusion

The Utility Commands and Help system form the backbone of the bot's transparency and administrative capabilities. By combining interactive Discord components with robust backend management functions, the system ensures that both casual users can find information easily and administrators can maintain the bot's health with minimal friction.