zumito-framework 1.19.0 → 1.21.0

package/dist/ZumitoFramework.js

@@ -22,6 +22,7 @@ import { SlashCommandRefresher } from './services/SlashCommandRefresher.js';
 import { ErrorHandler } from './services/handlers/ErrorHandler.js';
 import { ErrorType } from './definitions/ErrorType.js';
 import { MongoService } from './services/MongoService.js';
+import { registerDefaultExecutionRules } from './modules/core/baseModule/defaultRules.js';
 // import better-logging
 betterLogging(console);
 /**
@@ -165,6 +166,7 @@ export class ZumitoFramework {
         this.eventManager.addEventEmitter('discord', this.client);
         this.eventManager.addEventEmitter('framework', this.eventEmitter);
         await this.registerModules();
+        registerDefaultExecutionRules();
         await this.refreshSlashCommands();
         this.startApiServer();
         if (this.settings.statusOptions) {

package/dist/definitions/CommandExecutionRule.d.ts

@@ -0,0 +1,25 @@
+import { Command } from "./commands/Command.js";
+import { ZumitoFramework } from "../ZumitoFramework.js";
+import { Client, Guild, GuildMember, Message, CommandInteraction, ButtonInteraction, StringSelectMenuInteraction, ModalSubmitInteraction } from "discord.js";
+export type CommandExecutionType = 'prefix' | 'slash' | 'button' | 'selectMenu' | 'modal';
+export interface CommandExecutionContext {
+    command: Command;
+    type: CommandExecutionType;
+    framework: ZumitoFramework;
+    client: Client;
+    guild?: Guild;
+    member?: GuildMember;
+    guildSettings?: any;
+    message?: Message;
+    interaction?: CommandInteraction | ButtonInteraction | StringSelectMenuInteraction | ModalSubmitInteraction;
+    args?: Map<string, any>;
+}
+export interface CommandExecutionRule {
+    canRun: (context: CommandExecutionContext) => boolean | Promise<boolean>;
+    errorMessage?: string | ((context: CommandExecutionContext) => string);
+}
+export interface CommandExecutionCheck {
+    passed: boolean;
+    ruleName?: string;
+    message?: string;
+}

package/dist/definitions/CommandExecutionRule.js

@@ -0,0 +1 @@
+export {};

package/dist/definitions/commands/Command.d.ts

@@ -1,6 +1,7 @@
 import { CommandArgDefinition } from './CommandArgDefinition.js';
 import { CommandParameters, PrefixCommandParameters, SlashCommandParameters } from './CommandParameters.js';
 import { CommandBinds } from './CommandBinds.js';
+import type { CommandExecutionRule } from '../CommandExecutionRule.js';
 /**
  * @name Command
  * @description Base class for all commands
@@ -201,6 +202,24 @@ export declare abstract class Command {
      * @see {@link CommandType}
      */
     type: string;
+    /**
+     * @name rules
+     * @description Array of {@link CommandExecutionRule} that are checked before the command is executed.
+     * Each rule can block execution with a custom error message.
+     * @type {CommandExecutionRule[]}
+     * @default undefined
+     * @example
+     * ```ts
+     * export class PremiumCommand extends Command {
+     *   rules = [{
+     *     canRun: (ctx) => ctx.guildSettings?.premium === true,
+     *     errorMessage: 'This command requires a premium server.',
+     *   }];
+     * }
+     * ```
+     * @see {@link CommandExecutionRule}
+     */
+    rules?: CommandExecutionRule[];
     parent?: string;
     binds?: CommandBinds;
     /**

package/dist/definitions/commands/Command.js

@@ -199,6 +199,24 @@ export class Command {
      * @see {@link CommandType}
      */
     type = CommandType.any;
+    /**
+     * @name rules
+     * @description Array of {@link CommandExecutionRule} that are checked before the command is executed.
+     * Each rule can block execution with a custom error message.
+     * @type {CommandExecutionRule[]}
+     * @default undefined
+     * @example
+     * ```ts
+     * export class PremiumCommand extends Command {
+     *   rules = [{
+     *     canRun: (ctx) => ctx.guildSettings?.premium === true,
+     *     errorMessage: 'This command requires a premium server.',
+     *   }];
+     * }
+     * ```
+     * @see {@link CommandExecutionRule}
+     */
+    rules;
     parent;
     binds;
     async executePrefixCommand({ message, args, client, framework, trans, }) {

package/dist/index.d.ts

@@ -31,8 +31,11 @@ import { CommandManager } from './services/managers/CommandManager.js';
 import { ErrorType } from './definitions/ErrorType.js';
 import { InviteUrlGenerator } from './services/utilities/InviteUrlGenerator.js';
 import { PrefixResolver } from './services/utilities/PrefixResolver.js';
+import { CommandExecutionChecker } from './services/CommandExecutionChecker.js';
+export type { CommandExecutionRule, CommandExecutionContext, CommandExecutionCheck, CommandExecutionType } from './definitions/CommandExecutionRule.js';
 export { ModalSubmitParameters } from './definitions/parameters/ModalSubmitParameters.js';
 export { CommandBinds } from './definitions/commands/CommandBinds.js';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
 export { LauncherConfig } from './definitions/config/LauncherConfig.js';
-export { ZumitoFramework, FrameworkSettings, Command, Module, CommandParameters, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, SelectMenuParameters, CommandType, CommandArgDefinition, CommandChoiceDefinition, ButtonPressed, ButtonPressedParams, TextFormatter, EmojiFallback, DatabaseConfigLoader, PresenceDataRule, RuledPresenceData, StatusManagerOptions, discord, EventParameters, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, };
+export { ModuleParameters } from './definitions/parameters/ModuleParameters.js';
+export { ZumitoFramework, FrameworkSettings, Command, Module, CommandParameters, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, SelectMenuParameters, CommandType, CommandArgDefinition, CommandChoiceDefinition, ButtonPressed, ButtonPressedParams, TextFormatter, EmojiFallback, DatabaseConfigLoader, PresenceDataRule, RuledPresenceData, StatusManagerOptions, discord, EventParameters, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, CommandExecutionChecker, };

package/dist/index.js

@@ -24,6 +24,7 @@ import { CommandManager } from './services/managers/CommandManager.js';
 import { ErrorType } from './definitions/ErrorType.js';
 import { InviteUrlGenerator } from './services/utilities/InviteUrlGenerator.js';
 import { PrefixResolver } from './services/utilities/PrefixResolver.js';
+import { CommandExecutionChecker } from './services/CommandExecutionChecker.js';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
 ServiceContainer.addService(TextFormatter, []);
 ServiceContainer.addService(EmojiFallback, [discord.Client.name, TranslationManager.name]);
@@ -34,5 +35,6 @@ ServiceContainer.addService(SlashCommandRefresher, [ZumitoFramework.name]);
 ServiceContainer.addService(InteractionHandler, []);
 ServiceContainer.addService(InviteUrlGenerator, []);
 ServiceContainer.addService(PrefixResolver, []);
+ServiceContainer.addService(CommandExecutionChecker, [], true);
 ServiceContainer.addService(ErrorHandler, ['ZumitoFramework']);
-export { ZumitoFramework, Command, Module, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, CommandType, ButtonPressed, TextFormatter, EmojiFallback, DatabaseConfigLoader, discord, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, };
+export { ZumitoFramework, Command, Module, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, CommandType, ButtonPressed, TextFormatter, EmojiFallback, DatabaseConfigLoader, discord, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, CommandExecutionChecker, };

package/dist/launcher.js

@@ -6,16 +6,15 @@ import fs from 'fs';
 import { pathToFileURL } from 'url';
 import dotenv from 'dotenv';
 import { RecursiveObjectMerger } from './services/utilities/RecursiveObjectMerger';
+import { EnvValidator } from './services/utilities/EnvValidator';
+import { BotReadyLogger } from './services/utilities/BotReadyLogger';
 dotenv.config();
-if (!process.env.DISCORD_TOKEN) {
-    throw new Error("Discord Token not found (DISCORD_TOKEN)");
-}
-else if (!process.env.DISCORD_CLIENT_ID) {
-    throw new Error("Discord Client ID not found (DISCORD_CLIENT_ID)");
-}
-else if (!process.env.MONGO_URI) {
-    throw new Error("No MongoDB connection string specified in .env file (MONGO_URI)");
-}
+const REQUIRED_ENV_VARS = {
+    DISCORD_TOKEN: 'Discord Bot Token',
+    DISCORD_CLIENT_ID: 'Discord Client ID',
+    MONGO_URI: 'MongoDB connection URI',
+};
+EnvValidator.validate(REQUIRED_ENV_VARS);
 const defaultConfig = {
     discordClientOptions: {
         intents: 3276799,
@@ -35,16 +34,7 @@ import(pathToFileURL(configFilePath).href)
     .then(({ config: userConfig }) => {
     const config = RecursiveObjectMerger.merge(defaultConfig, userConfig);
     new ZumitoFramework(config, (bot) => {
-        // Log number of commands loaded
-        console.log(`Loaded ${bot.commands.size} commands`);
-        // Log number of events loaded
-        console.log(`Loaded ${bot.events.size} events`);
-        // Log number of modules loaded
-        console.log(`Loaded ${bot.modules.size} modules`);
-        // Log number of translations loaded
-        console.log(`Loaded ${bot.translations.getAll().size} translations`);
-        // Log number of routes registered
-        console.log(`Loaded ${bot.routes.length} routes`);
+        BotReadyLogger.log(bot);
         userConfig.callbacks?.load?.(bot);
     });
 })

package/dist/modules/core/baseModule/defaultRules.d.ts

@@ -0,0 +1 @@
+export declare function registerDefaultExecutionRules(): void;

package/dist/modules/core/baseModule/defaultRules.js

@@ -0,0 +1,82 @@
+import { PermissionsBitField, } from 'discord.js';
+import { CommandExecutionChecker, } from '../../../services/CommandExecutionChecker.js';
+import { ServiceContainer } from '../../../services/ServiceContainer.js';
+import { MemberPermissionChecker } from '../../../services/utilities/MemberPermissionChecker.js';
+async function isAdminOrOwner(ctx) {
+    if (!ctx.member || !ctx.guild)
+        return false;
+    if (ctx.member.id === ctx.guild.ownerId)
+        return true;
+    const permChecker = ServiceContainer.getService(MemberPermissionChecker);
+    return permChecker.hasPermissionOnChannel(ctx.member, ctx.guild.channels?.cache?.first?.() || {}, PermissionsBitField.Flags.Administrator);
+}
+async function checkUserPermissions(ctx) {
+    if (!ctx.member || !ctx.guild)
+        return false;
+    const permChecker = ServiceContainer.getService(MemberPermissionChecker);
+    const channel = (ctx.message?.channel ||
+        ctx.interaction?.channel);
+    for (const permission of ctx.command.userPermissions) {
+        if (!(await permChecker.hasPermissionOnChannel(ctx.member, channel, permission))) {
+            return false;
+        }
+    }
+    return true;
+}
+export function registerDefaultExecutionRules() {
+    const checker = ServiceContainer.getService(CommandExecutionChecker);
+    checker.addRule('no-bots', {
+        canRun: (ctx) => {
+            return !ctx.member?.user?.bot;
+        },
+        errorMessage: 'Bots cannot use commands.',
+    });
+    checker.addRule('dm-disabled', {
+        canRun: (ctx) => {
+            if (ctx.command.dm)
+                return true;
+            if (ctx.guild === null || ctx.guild === undefined)
+                return false;
+            return true;
+        },
+        errorMessage: 'This command cannot be used in DMs.',
+    });
+    checker.addRule('admin-only', {
+        canRun: async (ctx) => {
+            if (!ctx.command.adminOnly)
+                return true;
+            if (ctx.type === 'button' || ctx.type === 'selectMenu' || ctx.type === 'modal')
+                return true;
+            return isAdminOrOwner(ctx);
+        },
+        errorMessage: 'This command is restricted to administrators.',
+    });
+    checker.addRule('user-permissions', {
+        canRun: async (ctx) => {
+            if (!ctx.command.userPermissions || ctx.command.userPermissions.length === 0)
+                return true;
+            if (ctx.type === 'button' || ctx.type === 'selectMenu' || ctx.type === 'modal')
+                return true;
+            if (await isAdminOrOwner(ctx))
+                return true;
+            return checkUserPermissions(ctx);
+        },
+        errorMessage: (ctx) => `You do not have permission to use \`${ctx.command.name}\`.`,
+    });
+    checker.addRule('nsfw-only', {
+        canRun: async (ctx) => {
+            if (!ctx.command.nsfw)
+                return true;
+            if (ctx.type === 'button' || ctx.type === 'selectMenu' || ctx.type === 'modal')
+                return true;
+            if (await isAdminOrOwner(ctx))
+                return true;
+            const channel = (ctx.message?.channel ||
+                ctx.interaction?.channel);
+            if (!channel || !('nsfw' in channel))
+                return true;
+            return channel.nsfw === true;
+        },
+        errorMessage: 'This command can only be used in NSFW channels.',
+    });
+}

package/dist/modules/core/baseModule/events/discord/MessageCreate.js

@@ -1,4 +1,3 @@
-import { PermissionsBitField, } from 'discord.js';
 import { FrameworkEvent } from '../../../../../definitions/FrameworkEvent.js';
 import leven from 'leven';
 import { ServiceContainer } from '../../../../../services/ServiceContainer.js';
@@ -8,6 +7,7 @@ import { ZumitoFramework } from '../../../../../ZumitoFramework.js';
 import { GuildDataGetter } from '../../../../../services/utilities/GuildDataGetter.js';
 import { ErrorHandler } from '../../../../../services/handlers/ErrorHandler.js';
 import { ErrorType } from '../../../../../definitions/ErrorType.js';
+import { CommandExecutionChecker } from '../../../../../services/CommandExecutionChecker.js';
 export class MessageCreate extends FrameworkEvent {
     once = false;
     source = 'discord';
@@ -46,47 +46,6 @@ export class MessageCreate extends FrameworkEvent {
             commandInstance = Array.from(this.framework.commands.getAll().values()).find((c) => c.name == args.at(0) && c.parent && c.parent == command) || commandInstance;
             if (!commandInstance)
                 return;
-            if (message.guild == null && commandInstance.dm == false)
-                return;
-            if (commandInstance.adminOnly ||
-                commandInstance.userPermissions.length > 0) {
-                let denied = false;
-                if (this.memberPermissionChecker.hasPermissionOnChannel(message.member, message.channel, PermissionsBitField.Flags.Administrator) ||
-                    message.member.id != message.guild.ownerId) {
-                    if (commandInstance.userPermissions.length > 0) {
-                        commandInstance.userPermissions.forEach((permission) => {
-                            if (!this.memberPermissionChecker.hasPermissionOnChannel(message.member, message.channel, permission)) {
-                                denied = true;
-                            }
-                        });
-                    }
-                }
-                if (denied) {
-                    return message.reply({
-                        content: 'You do not have permission to use this command.',
-                        allowedMentions: {
-                            repliedUser: false,
-                        },
-                    });
-                }
-            }
-            if (message.channel.isTextBased) {
-                const channel = message.channel;
-                // Check command is nsfw and if channel is allowed
-                if (commandInstance.nsfw &&
-                    !channel.nsfw &&
-                    !channel
-                        .permissionsFor(message.member)
-                        .has(PermissionsBitField.Flags.Administrator) &&
-                    message.member.id != message.guild.ownerId) {
-                    return message.reply({
-                        content: 'This command is nsfw and this channel is not nsfw.',
-                        allowedMentions: {
-                            repliedUser: false,
-                        },
-                    });
-                }
-            }
             try {
                 const guildSettings = await this.guildDataGetter.getGuildSettings(message.guildId);
                 const parsedArgsResponse = await CommandParser.parseFromSplitedString(args, commandInstance.args, message.guild);
@@ -99,6 +58,24 @@ export class MessageCreate extends FrameworkEvent {
                     });
                 }
                 const parsedArgs = parsedArgsResponse.parsedArgs;
+                const executionChecker = ServiceContainer.getService(CommandExecutionChecker);
+                const check = await executionChecker.check({
+                    command: commandInstance,
+                    type: 'prefix',
+                    framework: this.framework,
+                    client: this.framework.client,
+                    guild: message.guild,
+                    member: message.member,
+                    guildSettings,
+                    message,
+                    args: parsedArgs,
+                });
+                if (!check.passed) {
+                    return message.reply({
+                        content: check.message || 'You cannot run this command.',
+                        allowedMentions: { repliedUser: false },
+                    });
+                }
                 await commandInstance.execute({
                     message,
                     args: parsedArgs,

package/dist/services/CommandExecutionChecker.d.ts

@@ -0,0 +1,10 @@
+import { CommandExecutionContext, CommandExecutionRule, CommandExecutionCheck } from "../definitions/CommandExecutionRule.js";
+export declare class CommandExecutionChecker {
+    private rules;
+    addRule(name: string, rule: CommandExecutionRule): void;
+    getRule(name: string): CommandExecutionRule | undefined;
+    removeRule(name: string): boolean;
+    getAllRules(): Map<string, CommandExecutionRule>;
+    check(context: CommandExecutionContext): Promise<CommandExecutionCheck>;
+    private evaluateRules;
+}

package/dist/services/CommandExecutionChecker.js

@@ -0,0 +1,53 @@
+export class CommandExecutionChecker {
+    rules = new Map();
+    addRule(name, rule) {
+        this.rules.set(name, rule);
+    }
+    getRule(name) {
+        return this.rules.get(name);
+    }
+    removeRule(name) {
+        return this.rules.delete(name);
+    }
+    getAllRules() {
+        return this.rules;
+    }
+    async check(context) {
+        const globalCheck = await this.evaluateRules('global', this.rules, context);
+        if (!globalCheck.passed)
+            return globalCheck;
+        const commandRules = context.command.rules;
+        if (commandRules && commandRules.length > 0) {
+            const commandRulesMap = new Map(commandRules.map((rule, i) => [`${context.command.name}:${i}`, rule]));
+            const commandCheck = await this.evaluateRules('command', commandRulesMap, context);
+            if (!commandCheck.passed)
+                return commandCheck;
+        }
+        return { passed: true };
+    }
+    async evaluateRules(scope, rules, context) {
+        for (const [name, rule] of rules) {
+            try {
+                const allowed = await rule.canRun(context);
+                if (!allowed) {
+                    const message = typeof rule.errorMessage === 'function'
+                        ? rule.errorMessage(context)
+                        : rule.errorMessage;
+                    return {
+                        passed: false,
+                        ruleName: `${scope}:${name}`,
+                        message,
+                    };
+                }
+            }
+            catch (err) {
+                return {
+                    passed: false,
+                    ruleName: `${scope}:${name}`,
+                    message: `Rule "${name}" threw an error: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        return { passed: true };
+    }
+}

package/dist/services/handlers/InteractionHandler.js

@@ -8,6 +8,7 @@ import { TranslationManager } from "../managers/TranslationManager";
 import { EventManager } from "../managers/EventManager";
 import { ErrorHandler } from "./ErrorHandler";
 import { ErrorType } from "../../definitions/ErrorType";
+import { CommandExecutionChecker } from "../CommandExecutionChecker";
 import 'reflect-metadata';
 export class InteractionHandler {
     commandManager;
@@ -91,6 +92,25 @@ export class InteractionHandler {
         if (!guildSettings && interaction.guildId) {
             guildSettings = await ServiceContainer.getService(GuildDataGetter).getGuildSettings(interaction.guildId);
         }
+        const executionChecker = ServiceContainer.getService(CommandExecutionChecker);
+        const check = await executionChecker.check({
+            command: commandInstance,
+            type: 'slash',
+            framework,
+            client: this.client,
+            guild: interaction.guild,
+            member: interaction.member,
+            guildSettings,
+            interaction,
+            args,
+        });
+        if (!check.passed) {
+            await interaction.reply({
+                content: check.message || 'You cannot run this command.',
+                ephemeral: true,
+            });
+            return;
+        }
         const trans = this.translationManager.getShortHandMethod('command.' + commandInstance.name, guildSettings?.lang);
         if (commandInstance.type === CommandType.separated ||
             commandInstance.type === CommandType.slash) {
@@ -136,6 +156,24 @@ export class InteractionHandler {
         if (!guildSettings && interaction.guildId) {
             guildSettings = await ServiceContainer.getService(GuildDataGetter).getGuildSettings(interaction.guildId);
         }
+        const executionChecker = ServiceContainer.getService(CommandExecutionChecker);
+        const check = await executionChecker.check({
+            command: commandInstance,
+            type: 'button',
+            framework,
+            client: this.client,
+            guild: interaction.guild,
+            member: interaction.member,
+            guildSettings,
+            interaction,
+        });
+        if (!check.passed) {
+            await interaction.reply({
+                content: check.message || 'You cannot use this button.',
+                ephemeral: true,
+            });
+            return;
+        }
         // If the command has impements ButtonPress class then execute the method
         if (commandInstance.constructor.prototype.hasOwnProperty('buttonPressed')) {
             commandInstance.buttonPressed({
@@ -155,8 +193,26 @@ export class InteractionHandler {
         if (!guildSettings && interaction.guildId) {
             guildSettings = await ServiceContainer.getService(GuildDataGetter).getGuildSettings(interaction.guildId);
         }
-        const trans = this.translationManager.getShortHandMethod('command.' + commandInstance.name, guildSettings?.lang);
         const framework = ServiceContainer.getService(ZumitoFramework);
+        const executionChecker = ServiceContainer.getService(CommandExecutionChecker);
+        const check = await executionChecker.check({
+            command: commandInstance,
+            type: 'selectMenu',
+            framework,
+            client: this.client,
+            guild: interaction.guild,
+            member: interaction.member,
+            guildSettings,
+            interaction,
+        });
+        if (!check.passed) {
+            await interaction.reply({
+                content: check.message || 'You cannot use this menu.',
+                ephemeral: true,
+            });
+            return;
+        }
+        const trans = this.translationManager.getShortHandMethod('command.' + commandInstance.name, guildSettings?.lang);
         if (commandInstance.binds?.selectMenu) {
             commandInstance.binds?.selectMenu({
                 path,
@@ -189,6 +245,24 @@ export class InteractionHandler {
             guildSettings = await ServiceContainer.getService(GuildDataGetter).getGuildSettings(interaction.guildId);
         }
         const framework = ServiceContainer.getService(ZumitoFramework);
+        const executionChecker = ServiceContainer.getService(CommandExecutionChecker);
+        const check = await executionChecker.check({
+            command: commandInstance,
+            type: 'modal',
+            framework,
+            client: this.client,
+            guild: interaction.guild,
+            member: interaction.member,
+            guildSettings,
+            interaction,
+        });
+        if (!check.passed) {
+            await interaction.reply({
+                content: check.message || 'You cannot submit this form.',
+                ephemeral: true,
+            });
+            return;
+        }
         if (commandInstance.binds?.modalSubmit) {
             const trans = this.translationManager.getShortHandMethod('command.' + commandInstance.name, guildSettings?.lang);
             commandInstance.binds.modalSubmit({

package/dist/services/utilities/BotReadyLogger.d.ts

@@ -0,0 +1,7 @@
+import { ZumitoFramework } from '../../ZumitoFramework';
+export declare class BotReadyLogger {
+    /**
+     * Log standard bot startup statistics (commands, events, modules, etc).
+     */
+    static log(bot: ZumitoFramework): void;
+}

package/dist/services/utilities/BotReadyLogger.js

@@ -0,0 +1,12 @@
+export class BotReadyLogger {
+    /**
+     * Log standard bot startup statistics (commands, events, modules, etc).
+     */
+    static log(bot) {
+        console.log(`Loaded ${bot.commands.size} commands`);
+        console.log(`Loaded ${bot.events.size} events`);
+        console.log(`Loaded ${bot.modules.size} modules`);
+        console.log(`Loaded ${bot.translations.getAll().size} translations`);
+        console.log(`Loaded ${bot.routes.length} routes`);
+    }
+}

package/dist/services/utilities/EnvValidator.d.ts

@@ -0,0 +1,9 @@
+export type EnvVarDefinitions = Record<string, string>;
+export declare class EnvValidator {
+    /**
+     * Validate that all required env vars are present. If any are missing,
+     * renders a visual error report and exits the process.
+     * @param required - Map of { KEY: 'Human label' }
+     */
+    static validate(required: EnvVarDefinitions): void;
+}

package/dist/services/utilities/EnvValidator.js

@@ -0,0 +1,50 @@
+import path from 'path';
+import fs from 'fs';
+import chalk from 'chalk';
+export class EnvValidator {
+    /**
+     * Validate that all required env vars are present. If any are missing,
+     * renders a visual error report and exits the process.
+     * @param required - Map of { KEY: 'Human label' }
+     */
+    static validate(required) {
+        const missing = [];
+        const present = [];
+        for (const [key] of Object.entries(required)) {
+            if (process.env[key]) {
+                present.push(key);
+            }
+            else {
+                missing.push(key);
+            }
+        }
+        if (missing.length === 0)
+            return;
+        const divider = chalk.yellow('━'.repeat(54));
+        const envPath = path.join(process.cwd(), '.env');
+        const hasEnvFile = fs.existsSync(envPath);
+        console.error(`\n${divider}`);
+        console.error(`  ${chalk.bold.red('CONFIGURATION ERROR')} — Missing environment variables`);
+        console.error(divider);
+        for (const key of present) {
+            const label = required[key];
+            const value = process.env[key];
+            const display = value.length > 28 ? value.slice(0, 25) + '...' : value;
+            console.error(`  ${chalk.green('✓')} ${chalk.green(key.padEnd(20))} ${chalk.dim(display)}`);
+        }
+        for (const key of missing) {
+            const label = required[key];
+            console.error(`  ${chalk.red('✗')} ${chalk.red(key.padEnd(20))} ${chalk.bold(label)}`);
+        }
+        console.error(divider);
+        if (!hasEnvFile) {
+            console.error(`  ${chalk.yellow('No .env file found in project root.')}`);
+            console.error(`  ${chalk.dim('Create one from .env.example and fill in the missing values.')}`);
+        }
+        else {
+            console.error(`  ${chalk.dim('.env file found but missing required variables.')}`);
+        }
+        console.error(divider + '\n');
+        process.exit(1);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zumito-framework",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Discord.js bot framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",