stoatx 0.7.6 → 0.8.0

package/dist/index.js

@@ -5,6 +5,7 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -33,6 +34,7 @@ var index_exports = {};
 __export(index_exports, {
   Client: () => Client,
   CommandRegistry: () => CommandRegistry,
+  CommandValidationError: () => CommandValidationError,
   DefaultCooldownManager: () => DefaultCooldownManager,
   Guard: () => Guard,
   METADATA_KEYS: () => METADATA_KEYS,
@@ -61,6 +63,9 @@ var METADATA_KEYS = {
 
 // src/decorators/store.ts
 var DecoratorStore = class _DecoratorStore {
+  static {
+    __name(this, "DecoratorStore");
+  }
   static instance;
   /** Stoat classes with their SimpleCommand methods */
   stoatClasses = /* @__PURE__ */ new Map();
@@ -77,8 +82,8 @@ var DecoratorStore = class _DecoratorStore {
     return _DecoratorStore.instance;
   }
   /**
-   * Register a @Stoat decorated class
-   */
+  * Register a @Stoat decorated class
+  */
   registerStoatClass(classConstructor) {
     if (!this.stoatClasses.has(classConstructor)) {
       const instance = new classConstructor();
@@ -86,40 +91,40 @@ var DecoratorStore = class _DecoratorStore {
     }
   }
   /**
-   * Get all registered Stoat classes with their instances
-   */
+  * Get all registered Stoat classes with their instances
+  */
   getStoatClasses() {
     return this.stoatClasses;
   }
   /**
-   * Add a registered command
-   */
+  * Add a registered command
+  */
   addCommand(command) {
     this.commands.push(command);
   }
   /**
-   * Get all registered commands
-   */
+  * Get all registered commands
+  */
   getCommands() {
     return this.commands;
   }
   /**
-   * Clear all registered classes (useful for testing)
-   */
+  * Clear all registered classes (useful for testing)
+  */
   clear() {
     this.stoatClasses.clear();
     this.commands = [];
     this.initialized = false;
   }
   /**
-   * Mark as initialized
-   */
+  * Mark as initialized
+  */
   markInitialized() {
     this.initialized = true;
   }
   /**
-   * Check if initialized
-   */
+  * Check if initialized
+  */
   isInitialized() {
     return this.initialized;
   }
@@ -133,9 +138,11 @@ function Stoat() {
     decoratorStore.registerStoatClass(target);
   };
 }
+__name(Stoat, "Stoat");
 function isStoatClass(target) {
   return Reflect.getMetadata(METADATA_KEYS.IS_STOAT_CLASS, target) === true;
 }
+__name(isStoatClass, "isStoatClass");
 
 // src/decorators/SimpleCommand.ts
 var import_reflect_metadata2 = require("reflect-metadata");
@@ -151,9 +158,11 @@ function SimpleCommand(options = {}) {
     return descriptor;
   };
 }
+__name(SimpleCommand, "SimpleCommand");
 function getSimpleCommands(target) {
   return Reflect.getMetadata(METADATA_KEYS.SIMPLE_COMMANDS, target) || [];
 }
+__name(getSimpleCommands, "getSimpleCommands");
 
 // src/decorators/Guard.ts
 var import_reflect_metadata3 = require("reflect-metadata");
@@ -164,9 +173,11 @@ function Guard(guardClass) {
     Reflect.defineMetadata(METADATA_KEYS.GUARDS, existingGuards, target);
   };
 }
+__name(Guard, "Guard");
 function getGuards(target) {
   return Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
 }
+__name(getGuards, "getGuards");
 
 // src/decorators/Events.ts
 var import_reflect_metadata4 = require("reflect-metadata");
@@ -183,15 +194,19 @@ function createEventDecorator(event, type) {
     return descriptor;
   };
 }
+__name(createEventDecorator, "createEventDecorator");
 function On(event) {
   return createEventDecorator(event, "on");
 }
+__name(On, "On");
 function Once(event) {
   return createEventDecorator(event, "once");
 }
+__name(Once, "Once");
 function getEventsMetadata(target) {
   return Reflect.getMetadata(METADATA_KEYS.EVENTS, target) || [];
 }
+__name(getEventsMetadata, "getEventsMetadata");
 
 // src/decorators/utils.ts
 function buildSimpleCommandMetadata(options, methodName, category) {
@@ -202,11 +217,16 @@ function buildSimpleCommandMetadata(options, methodName, category) {
     permissions: options.permissions ?? [],
     category: options.category ?? category ?? "uncategorized",
     cooldown: options.cooldown ?? 0,
-    ...options.cooldownStorage !== void 0 ? { cooldownStorage: options.cooldownStorage } : {},
+    ...options.cooldownStorage !== void 0 ? {
+      cooldownStorage: options.cooldownStorage
+    } : {},
     nsfw: options.nsfw ?? false,
-    ownerOnly: options.ownerOnly ?? false
+    ownerOnly: options.ownerOnly ?? false,
+    options: options.options ?? [],
+    args: options.args ?? []
   };
 }
+__name(buildSimpleCommandMetadata, "buildSimpleCommandMetadata");
 
 // src/registry.ts
 var path = __toESM(require("path"));
@@ -214,6 +234,9 @@ var fs = __toESM(require("fs/promises"));
 var import_node_url = require("url");
 var import_tinyglobby = require("tinyglobby");
 var CommandRegistry = class _CommandRegistry {
+  static {
+    __name(this, "CommandRegistry");
+  }
   static DEFAULT_AUTO_DISCOVERY_IGNORES = [
     "**/node_modules/**",
     "**/.git/**",
@@ -226,23 +249,31 @@ var CommandRegistry = class _CommandRegistry {
   registeredEvents = [];
   extensions;
   processedStoatClasses = /* @__PURE__ */ new Set();
-  constructor(extensions = [".js", ".mjs", ".cjs"]) {
+  constructor(extensions = [
+    ".js",
+    ".mjs",
+    ".cjs"
+  ]) {
     this.extensions = extensions;
   }
   /**
-   * Get the number of registered commands
-   */
+  * Get the number of registered commands
+  */
   get size() {
     return this.commands.size;
   }
   /**
-   * Load commands from a directory using glob pattern matching
-   */
+  * Load commands from a directory using glob pattern matching
+  */
   async loadFromDirectory(directory) {
     const patterns = this.extensions.map((ext) => path.join(directory, "**", `*${ext}`).replace(/\\/g, "/"));
     for (const pattern of patterns) {
       const files = await (0, import_tinyglobby.glob)(pattern, {
-        ignore: ["**/*.d.ts", "**/*.test.ts", "**/*.spec.ts"],
+        ignore: [
+          "**/*.d.ts",
+          "**/*.test.ts",
+          "**/*.spec.ts"
+        ],
         absolute: true
       });
       for (const file of files) {
@@ -252,19 +283,24 @@ var CommandRegistry = class _CommandRegistry {
     console.log(`[Stoatx] Loaded ${this.commands.size} command(s) and ${this.registeredEvents.length} event(s)`);
   }
   /**
-   * Auto-discover command files across one or more roots.
-   */
+  * Auto-discover command files across one or more roots.
+  */
   async autoDiscover(options = {}) {
-    const roots = options.roots?.length ? options.roots : [process.cwd()];
+    const roots = options.roots?.length ? options.roots : [
+      process.cwd()
+    ];
     const includePatterns = options.include?.length ? options.include : this.getDefaultAutoDiscoveryPatterns();
-    const patterns = roots.flatMap(
-      (root) => includePatterns.map((pattern) => path.join(root, pattern).replace(/\\/g, "/"))
-    );
+    const patterns = roots.flatMap((root) => includePatterns.map((pattern) => path.join(root, pattern).replace(/\\/g, "/")));
     const files = await (0, import_tinyglobby.glob)(patterns, {
-      ignore: [..._CommandRegistry.DEFAULT_AUTO_DISCOVERY_IGNORES, ...options.ignore ?? []],
+      ignore: [
+        ..._CommandRegistry.DEFAULT_AUTO_DISCOVERY_IGNORES,
+        ...options.ignore ?? []
+      ],
       absolute: true
     });
-    const uniqueFiles = [...new Set(files)];
+    const uniqueFiles = [
+      ...new Set(files)
+    ];
     let candidateFiles = 0;
     for (const file of uniqueFiles) {
       if (!await this.isLikelyCommandModule(file)) {
@@ -291,8 +327,8 @@ var CommandRegistry = class _CommandRegistry {
     }
   }
   /**
-   * Register a command instance
-   */
+  * Register a command instance
+  */
   register(instance, metadata, classConstructor, methodName) {
     const name = metadata.name.toLowerCase();
     if (this.commands.has(name)) {
@@ -300,7 +336,12 @@ var CommandRegistry = class _CommandRegistry {
       return;
     }
     this.validateGuards(classConstructor, metadata.name);
-    this.commands.set(name, { instance, metadata, methodName, classConstructor });
+    this.commands.set(name, {
+      instance,
+      metadata,
+      methodName,
+      classConstructor
+    });
     for (const alias of metadata.aliases) {
       const aliasLower = alias.toLowerCase();
       if (this.aliases.has(aliasLower) || this.commands.has(aliasLower)) {
@@ -311,41 +352,41 @@ var CommandRegistry = class _CommandRegistry {
     }
   }
   /**
-   * Get a command by name or alias
-   */
+  * Get a command by name or alias
+  */
   get(name) {
     const lowerName = name.toLowerCase();
     const resolvedName = this.aliases.get(lowerName) ?? lowerName;
     return this.commands.get(resolvedName);
   }
   /**
-   * Check if a command exists
-   */
+  * Check if a command exists
+  */
   has(name) {
     const lowerName = name.toLowerCase();
     return this.commands.has(lowerName) || this.aliases.has(lowerName);
   }
   /**
-   * Get all registered commands
-   */
+  * Get all registered commands
+  */
   getAll() {
     return Array.from(this.commands.values());
   }
   /**
-   * Get all command metadata
-   */
+  * Get all command metadata
+  */
   getAllMetadata() {
     return this.getAll().map((c) => c.metadata);
   }
   /**
-   * Get all registered events
-   */
+  * Get all registered events
+  */
   getEvents() {
     return this.registeredEvents;
   }
   /**
-   * Get commands grouped by category
-   */
+  * Get commands grouped by category
+  */
   getByCategory() {
     const categories = /* @__PURE__ */ new Map();
     for (const cmd of this.commands.values()) {
@@ -357,8 +398,8 @@ var CommandRegistry = class _CommandRegistry {
     return categories;
   }
   /**
-   * Clear all commands
-   */
+  * Clear all commands
+  */
   clear() {
     this.commands.clear();
     this.aliases.clear();
@@ -366,51 +407,47 @@ var CommandRegistry = class _CommandRegistry {
     this.processedStoatClasses.clear();
   }
   /**
-   * Iterate over commands
-   */
+  * Iterate over commands
+  */
   [Symbol.iterator]() {
     return this.commands.entries();
   }
   /**
-   * Iterate over command values
-   */
+  * Iterate over command values
+  */
   values() {
     return this.commands.values();
   }
   /**
-   * Iterate over command names
-   */
+  * Iterate over command names
+  */
   keys() {
     return this.commands.keys();
   }
   /**
-   * Validate that all guards on a command implement the required methods
-   * @param commandClass
-   * @param commandName
-   * @private
-   */
+  * Validate that all guards on a command implement the required methods
+  * @param commandClass
+  * @param commandName
+  * @private
+  */
   validateGuards(commandClass, commandName) {
     const guards = Reflect.getMetadata("stoatx:command:guards", commandClass) || [];
     for (const GuardClass of guards) {
       const guardInstance = new GuardClass();
       if (typeof guardInstance.run !== "function") {
-        console.error(
-          `[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`
-        );
+        console.error(`[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`);
         process.exit(1);
       }
       if (typeof guardInstance.guardFail !== "function") {
-        console.error(
-          `[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`
-        );
+        console.error(`[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`);
         console.error(`[Stoatx] All guards must implement guardFail() to handle failed checks.`);
         process.exit(1);
       }
     }
   }
   /**
-   * Load commands from a single file
-   */
+  * Load commands from a single file
+  */
   async loadFile(filePath, baseDir) {
     try {
       const knownStoatClasses = new Set(decoratorStore.getStoatClasses().keys());
@@ -432,9 +469,7 @@ var CommandRegistry = class _CommandRegistry {
     const events = getEventsMetadata(stoatClass);
     const category = this.getCategoryFromPath(filePath, baseDir);
     if (simpleCommands.length === 0 && events.length === 0) {
-      console.warn(
-        `[Stoatx] Class ${stoatClass.name} is decorated with @Stoat but has no @SimpleCommand, @On or @Once methods. Skipping...`
-      );
+      console.warn(`[Stoatx] Class ${stoatClass.name} is decorated with @Stoat but has no @SimpleCommand, @On or @Once methods. Skipping...`);
       this.processedStoatClasses.add(stoatClass);
       return;
     }
@@ -463,8 +498,8 @@ var CommandRegistry = class _CommandRegistry {
     this.processedStoatClasses.add(stoatClass);
   }
   /**
-   * Derive category from file path relative to base directory
-   */
+  * Derive category from file path relative to base directory
+  */
   getCategoryFromPath(filePath, baseDir) {
     const relative2 = path.relative(baseDir, filePath);
     const parts = relative2.split(path.sep);
@@ -477,8 +512,24 @@ var CommandRegistry = class _CommandRegistry {
 
 // src/handler.ts
 var import_reflect_metadata5 = require("reflect-metadata");
-var import_client = require("@stoatx/client");
+
+// src/error.ts
+var CommandValidationError = class extends Error {
+  static {
+    __name(this, "CommandValidationError");
+  }
+  optionName;
+  constructor(optionName, message) {
+    super(message), this.optionName = optionName;
+    this.name = "CommandValidationError";
+  }
+};
+
+// src/handler.ts
 var DefaultCooldownManager = class {
+  static {
+    __name(this, "DefaultCooldownManager");
+  }
   cooldowns = /* @__PURE__ */ new Map();
   check(ctx, metadata) {
     if (metadata.cooldown <= 0) return true;
@@ -510,23 +561,10 @@ var DefaultCooldownManager = class {
     this.cooldowns.clear();
   }
 };
-var Client = class extends import_client.Client {
-  handler;
-  constructor(options) {
-    super();
-    this.handler = new StoatxHandler({ ...options, client: this });
-    this.on("messageCreate", async (message) => {
-      await this.handler.handle(message);
-    });
-  }
-  /**
-   * Initialize the StoatxHandler commands
-   */
-  async initCommands() {
-    await this.handler.init();
-  }
-};
 var StoatxHandler = class {
+  static {
+    __name(this, "StoatxHandler");
+  }
   commandsDir;
   discoveryOptions;
   prefixResolver;
@@ -535,6 +573,7 @@ var StoatxHandler = class {
   cooldownManager;
   disableMentionPrefix;
   client;
+  flagPrefix;
   constructor(options) {
     this.client = options.client;
     this.commandsDir = options.commandsDir;
@@ -544,10 +583,11 @@ var StoatxHandler = class {
     this.registry = new CommandRegistry(options.extensions);
     this.disableMentionPrefix = options.disableMentionPrefix ?? false;
     this.cooldownManager = options.cooldownManager ?? new DefaultCooldownManager();
+    this.flagPrefix = options.flagPrefix || "-";
   }
   /**
-   * Initialize the handler - load all commands
-   */
+  * Initialize the handler - load all commands
+  */
   async init() {
     if (this.commandsDir) {
       await this.registry.loadFromDirectory(this.commandsDir);
@@ -557,21 +597,18 @@ var StoatxHandler = class {
     this.attachEvents();
   }
   /**
-   * Attach registered events to the client
-   */
+  * Attach registered events to the client
+  */
   attachEvents() {
     const events = this.registry.getEvents();
     for (const eventDef of events) {
-      const handler = async (...args) => {
+      const handler = /* @__PURE__ */ __name(async (...args) => {
         try {
           await eventDef.instance[eventDef.methodName](...args, this.client);
         } catch (error) {
-          console.error(
-            `[Stoatx] Event Handler Error in @${eventDef.type === "on" ? "On" : "Once"}('${eventDef.event}'):`,
-            error
-          );
+          console.error(`[Stoatx] Event Handler Error in @${eventDef.type === "on" ? "On" : "Once"}('${eventDef.event}'):`, error);
         }
-      };
+      }, "handler");
       const eventName = eventDef.event;
       if (eventDef.type === "once") {
         this.client.once(eventName, handler);
@@ -581,8 +618,38 @@ var StoatxHandler = class {
     }
   }
   /**
-   * Parse a raw message into command context
-   */
+  * Parses raw string arguments into positional args and key-value options
+  */
+  parseCommandOptions(rawArgs) {
+    const args = [];
+    const options = {};
+    for (let i = 0; i < rawArgs.length; i++) {
+      const arg = rawArgs[i];
+      if (arg === void 0) continue;
+      if (arg.startsWith(this.flagPrefix)) {
+        let key = arg;
+        while (key.startsWith(this.flagPrefix)) {
+          key = key.slice(this.flagPrefix.length);
+        }
+        const nextArg = rawArgs[i + 1];
+        if (nextArg !== void 0 && !nextArg.startsWith(this.flagPrefix)) {
+          options[key] = nextArg;
+          i++;
+        } else {
+          options[key] = true;
+        }
+      } else {
+        args.push(arg);
+      }
+    }
+    return {
+      args,
+      options
+    };
+  }
+  /**
+  * Parse a raw message into command context
+  */
   async parseMessage(rawContent, message, meta) {
     const prefix = await this.resolvePrefix(meta.serverId);
     let usedPrefix = prefix;
@@ -605,10 +672,11 @@ var StoatxHandler = class {
     if (!withoutPrefix) {
       return null;
     }
-    const [commandName, ...args] = withoutPrefix.split(/\s+/);
+    const [commandName, ...rawArgs] = withoutPrefix.split(/\s+/);
     if (!commandName) {
       return null;
     }
+    const { args, options } = this.parseCommandOptions(rawArgs);
     return {
       client: this.client,
       content: rawContent,
@@ -616,6 +684,7 @@ var StoatxHandler = class {
       channelId: meta.channelId,
       serverId: meta.serverId,
       args,
+      options,
       prefix: usedPrefix,
       commandName: commandName.toLowerCase(),
       reply: meta.reply,
@@ -623,16 +692,16 @@ var StoatxHandler = class {
     };
   }
   /**
-   * Handle a message object using the configured message adapter
-   *
-   * @example
-   * ```ts
-   * // With message adapter configured
-   * client.on('messageCreate', (message) => {
-   *   handler.handle(message);
-   * });
-   * ```
-   */
+  * Handle a message object using the configured message adapter
+  *
+  * @example
+  * ```ts
+  * // With message adapter configured
+  * client.on('messageCreate', (message) => {
+  *   handler.handle(message);
+  * });
+  * ```
+  */
   async handle(message) {
     if (!message.channel || !message.author || !message.content) {
       return false;
@@ -644,9 +713,9 @@ var StoatxHandler = class {
     const authorId = message.author.id;
     const channelId = message.channel.id;
     const serverId = message.server?.id;
-    const reply = async (content) => {
+    const reply = /* @__PURE__ */ __name(async (content) => {
       return await message.channel.send(content);
-    };
+    }, "reply");
     await this.handleMessage(rawContent, message, {
       authorId,
       channelId,
@@ -656,21 +725,21 @@ var StoatxHandler = class {
     return true;
   }
   /**
-   * Handle a raw message string with metadata
-   *
-   * @example
-   * ```ts
-   * // Manual usage without message adapter
-   * client.on('messageCreate', (message) => {
-   *   handler.handleMessage(message.content, message, {
-   *     authorId: message.author.id,
-   *     channelId: message.channel.id,
-   *     serverId: message.server?.id,
-   *     reply: (content) => message.channel.sendMessage(content),
-   *   });
-   * });
-   * ```
-   */
+  * Handle a raw message string with metadata
+  *
+  * @example
+  * ```ts
+  * // Manual usage without message adapter
+  * client.on('messageCreate', (message) => {
+  *   handler.handleMessage(message.content, message, {
+  *     authorId: message.author.id,
+  *     channelId: message.channel.id,
+  *     serverId: message.server?.id,
+  *     reply: (content) => message.channel.sendMessage(content),
+  *   });
+  * });
+  * ```
+  */
   async handleMessage(rawContent, message, meta) {
     const ctx = await this.parseMessage(rawContent, message, meta);
     if (!ctx) {
@@ -679,14 +748,15 @@ var StoatxHandler = class {
     await this.execute(ctx);
   }
   /**
-   * Execute a command with the given context
-   */
+  * Execute a command with the given context
+  */
   async execute(ctx) {
     const registered = this.registry.get(ctx.commandName);
     if (!registered) {
       return false;
     }
     const { instance, metadata, methodName, classConstructor } = registered;
+    console.log(`[Debug] Metadata options for ${ctx.commandName}:`, metadata.options);
     if (metadata.ownerOnly && !this.owners.has(ctx.authorId)) {
       await ctx.reply("This command is owner-only.");
       return false;
@@ -719,6 +789,190 @@ var StoatxHandler = class {
         }
       }
     }
+    if (metadata.args) {
+      const finalArgs = [];
+      for (let i = 0; i < metadata.args.length; i++) {
+        const def = metadata.args[i];
+        const rawValue = ctx.args[i];
+        if (def === void 0) continue;
+        if (rawValue === void 0) {
+          if (def.required) {
+            try {
+              throw new CommandValidationError(def.name, `Missing required argument: \`<${def.name}>\``);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Missing required argument: \`<${def.name}>\``);
+              }
+              return false;
+            }
+          }
+          break;
+        }
+        if (def.type === "number") {
+          const numValue = Number(rawValue);
+          if (isNaN(numValue)) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid value for \`<${def.name}>\`. Expected a number.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid value for \`<${def.name}>\`. Expected a number.`);
+              }
+              return false;
+            }
+          }
+          finalArgs[i] = numValue;
+        } else if (def.type === "boolean") {
+          finalArgs[i] = rawValue === "false" ? false : Boolean(rawValue);
+        } else if (def.type === "user") {
+          const match = String(rawValue).match(/^(?:<@)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid user mention for \`<${def.name}>\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid user mention for \`<${def.name}>\`.`);
+              }
+              return false;
+            }
+          }
+          finalArgs[i] = match[1];
+        } else if (def.type === "channel") {
+          const match = String(rawValue).match(/^(?:<#)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid channel mention for \`<${def.name}>\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid channel mention for \`<${def.name}>\`.`);
+              }
+              return false;
+            }
+          }
+          finalArgs[i] = match[1];
+        } else if (def.type === "role") {
+          const match = String(rawValue).match(/^(?:<%)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid role mention for \`<${def.name}>\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid role mention for \`<${def.name}>\`.`);
+              }
+              return false;
+            }
+          }
+          finalArgs[i] = match[1];
+        } else {
+          finalArgs[i] = String(rawValue);
+        }
+      }
+      if (ctx.args.length > metadata.args.length) {
+        for (let i = metadata.args.length; i < ctx.args.length; i++) {
+          if (ctx.args[i] !== void 0) {
+            finalArgs.push(ctx.args[i]);
+          }
+        }
+      }
+      ctx.args = finalArgs;
+    }
+    const finalOptions = {};
+    const currentOptions = ctx.options || {};
+    if (metadata.options) {
+      for (const def of metadata.options) {
+        const rawValue = currentOptions[def.name];
+        if (rawValue === void 0) {
+          if (def.required) {
+            try {
+              throw new CommandValidationError(def.name, `Missing required option: \`--${def.name}\``);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Missing required option: \`--${def.name}\``);
+              }
+              return false;
+            }
+          }
+          continue;
+        }
+        if (def.type === "number") {
+          const numValue = Number(rawValue);
+          if (isNaN(numValue)) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid value for \`--${def.name}\`. Expected a number.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid value for \`--${def.name}\`. Expected a number.`);
+              }
+              return false;
+            }
+          }
+          finalOptions[def.name] = numValue;
+        } else if (def.type === "boolean") {
+          finalOptions[def.name] = rawValue === "false" ? false : Boolean(rawValue);
+        } else if (def.type === "user") {
+          const match = String(rawValue).match(/^(?:<@)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid user mention for \`--${def.name}\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid user mention for \`--${def.name}\`.`);
+              }
+              return false;
+            }
+          }
+          finalOptions[def.name] = match[1];
+        } else if (def.type === "channel") {
+          const match = String(rawValue).match(/^(?:<#)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid channel mention for \`--${def.name}\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid channel mention for \`--${def.name}\`.`);
+              }
+              return false;
+            }
+          }
+          finalOptions[def.name] = match[1];
+        } else if (def.type === "role") {
+          const match = String(rawValue).match(/^(?:<%)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+          if (!match) {
+            try {
+              throw new CommandValidationError(def.name, `Invalid role mention for \`--${def.name}\`.`);
+            } catch (error) {
+              if (typeof instance.onError === "function") {
+                await instance.onError(ctx, error);
+              } else {
+                await ctx.reply(`Invalid role mention for \`--${def.name}\`.`);
+              }
+              return false;
+            }
+          }
+          finalOptions[def.name] = match[1];
+        } else {
+          finalOptions[def.name] = String(rawValue);
+        }
+      }
+      ctx.options = finalOptions;
+    }
     if (!await this.cooldownManager.check(ctx, metadata)) {
       const remaining = await this.cooldownManager.getRemaining(ctx, metadata);
       if (typeof instance.onCooldown === "function") {
@@ -744,26 +998,26 @@ var StoatxHandler = class {
     }
   }
   /**
-   * Get the command registry
-   */
+  * Get the command registry
+  */
   getRegistry() {
     return this.registry;
   }
   /**
-   * Get a command by name or alias
-   */
+  * Get a command by name or alias
+  */
   getCommand(name) {
     return this.registry.get(name);
   }
   /**
-   * Get all commands
-   */
+  * Get all commands
+  */
   getCommands() {
     return this.registry.getAll();
   }
   /**
-   * Reload all commands
-   */
+  * Reload all commands
+  */
   async reload() {
     this.registry.clear();
     if (this.cooldownManager.clear) {
@@ -776,40 +1030,66 @@ var StoatxHandler = class {
     await this.registry.autoDiscover(this.discoveryOptions);
   }
   /**
-   * Check if a user is an owner
-   */
+  * Check if a user is an owner
+  */
   isOwner(userId) {
     return this.owners.has(userId);
   }
   /**
-   * Add an owner
-   */
+  * Add an owner
+  */
   addOwner(userId) {
     this.owners.add(userId);
   }
   /**
-   * Remove an owner
-   */
+  * Remove an owner
+  */
   removeOwner(userId) {
     this.owners.delete(userId);
   }
   /**
-   * Resolve the prefix for a context
-   */
+  * Resolve the prefix for a context
+  */
   async resolvePrefix(serverId) {
     if (typeof this.prefixResolver === "function") {
-      return this.prefixResolver({ serverId });
+      return this.prefixResolver({
+        serverId
+      });
     }
     return this.prefixResolver;
   }
 };
 
+// src/client.ts
+var import_client = require("@stoatx/client");
+var Client = class extends import_client.Client {
+  static {
+    __name(this, "Client");
+  }
+  handler;
+  constructor(options) {
+    super(options);
+    this.handler = new StoatxHandler({
+      ...options,
+      client: this
+    });
+  }
+  async login(token) {
+    await this.handler.init();
+    return super.login(token);
+  }
+  async executeCommand(message) {
+    await this.handler.handle(message);
+  }
+};
+
 // src/index.ts
 __reExport(index_exports, require("@stoatx/client"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Client,
   CommandRegistry,
+  CommandValidationError,
   DefaultCooldownManager,
   Guard,
   METADATA_KEYS,