stoatx 0.8.0 → 1.0.1

package/dist/index.mjs

@@ -1,6 +1,35 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
+// src/types.ts
+import { User, BaseChannel, Role } from "@stoatx/client";
+var PARAM_TYPE_MAP = /* @__PURE__ */ new Map([
+  [
+    String,
+    "string"
+  ],
+  [
+    Number,
+    "number"
+  ],
+  [
+    Boolean,
+    "boolean"
+  ],
+  [
+    User,
+    "user"
+  ],
+  [
+    BaseChannel,
+    "channel"
+  ],
+  [
+    Role,
+    "role"
+  ]
+]);
+
 // src/decorators/Stoat.ts
 import "reflect-metadata";
 
@@ -9,7 +38,12 @@ var METADATA_KEYS = {
   IS_STOAT_CLASS: /* @__PURE__ */ Symbol("stoatx:stoat:isClass"),
   SIMPLE_COMMANDS: /* @__PURE__ */ Symbol("stoatx:stoat:simpleCommands"),
   GUARDS: "stoatx:command:guards",
-  EVENTS: /* @__PURE__ */ Symbol("stoatx:stoat:events")
+  EVENTS: /* @__PURE__ */ Symbol("stoatx:stoat:events"),
+  ARGS: /* @__PURE__ */ Symbol("stoatx:param:args"),
+  OPTIONS: /* @__PURE__ */ Symbol("stoatx:param:options"),
+  INJECTABLE: /* @__PURE__ */ Symbol("stoatx:injectable"),
+  SUBCOMMAND: /* @__PURE__ */ Symbol("stoatx:subcommand"),
+  COMMAND_GROUP: /* @__PURE__ */ Symbol("stoatx:commandGroup")
 };
 
 // src/decorators/store.ts
@@ -19,7 +53,7 @@ var DecoratorStore = class _DecoratorStore {
   }
   static instance;
   /** Stoat classes with their SimpleCommand methods */
-  stoatClasses = /* @__PURE__ */ new Map();
+  stoatClasses = /* @__PURE__ */ new Set();
   /** Registered commands from @Stoat/@SimpleCommand decorators */
   commands = [];
   /** Whether the store has been initialized */
@@ -36,10 +70,7 @@ var DecoratorStore = class _DecoratorStore {
   * Register a @Stoat decorated class
   */
   registerStoatClass(classConstructor) {
-    if (!this.stoatClasses.has(classConstructor)) {
-      const instance = new classConstructor();
-      this.stoatClasses.set(classConstructor, instance);
-    }
+    this.stoatClasses.add(classConstructor);
   }
   /**
   * Get all registered Stoat classes with their instances
@@ -118,14 +149,23 @@ __name(getSimpleCommands, "getSimpleCommands");
 // src/decorators/Guard.ts
 import "reflect-metadata";
 function Guard(guardClass) {
-  return (target) => {
-    const existingGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
-    existingGuards.push(guardClass);
-    Reflect.defineMetadata(METADATA_KEYS.GUARDS, existingGuards, target);
+  return (target, propertyKey) => {
+    if (propertyKey) {
+      const existingGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, target, propertyKey) || [];
+      existingGuards.push(guardClass);
+      Reflect.defineMetadata(METADATA_KEYS.GUARDS, existingGuards, target, propertyKey);
+    } else {
+      const existingGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
+      existingGuards.push(guardClass);
+      Reflect.defineMetadata(METADATA_KEYS.GUARDS, existingGuards, target);
+    }
   };
 }
 __name(Guard, "Guard");
-function getGuards(target) {
+function getGuards(target, propertyKey) {
+  if (propertyKey) {
+    return Reflect.getMetadata(METADATA_KEYS.GUARDS, target.prototype, propertyKey) || [];
+  }
   return Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
 }
 __name(getGuards, "getGuards");
@@ -159,8 +199,74 @@ function getEventsMetadata(target) {
 }
 __name(getEventsMetadata, "getEventsMetadata");
 
+// src/decorators/Arg.ts
+import "reflect-metadata";
+function Arg(options = {}) {
+  return (target, propertyKey, parameterIndex) => {
+    const existing = Reflect.getMetadata(METADATA_KEYS.ARGS, target, propertyKey) || [];
+    existing.push({
+      ...options,
+      index: parameterIndex
+    });
+    Reflect.defineMetadata(METADATA_KEYS.ARGS, existing, target, propertyKey);
+  };
+}
+__name(Arg, "Arg");
+function getArgs(target, propertyKey) {
+  return Reflect.getMetadata(METADATA_KEYS.ARGS, target, propertyKey) || [];
+}
+__name(getArgs, "getArgs");
+
+// src/decorators/Option.ts
+import "reflect-metadata";
+function Option(options) {
+  return (target, propertyKey, parameterIndex) => {
+    const existing = Reflect.getMetadata(METADATA_KEYS.OPTIONS, target, propertyKey) || [];
+    existing.push({
+      ...options,
+      index: parameterIndex
+    });
+    Reflect.defineMetadata(METADATA_KEYS.OPTIONS, existing, target, propertyKey);
+  };
+}
+__name(Option, "Option");
+function getOptions(target, propertyKey) {
+  return Reflect.getMetadata(METADATA_KEYS.OPTIONS, target, propertyKey) || [];
+}
+__name(getOptions, "getOptions");
+
+// src/decorators/Injectable.ts
+import "reflect-metadata";
+function Injectable() {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+  };
+}
+__name(Injectable, "Injectable");
+
+// src/decorators/CommandGroup.ts
+import "reflect-metadata";
+function CommandGroup(name) {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.COMMAND_GROUP, name, target);
+  };
+}
+__name(CommandGroup, "CommandGroup");
+
+// src/decorators/SubCommand.ts
+import "reflect-metadata";
+function SubCommand(options) {
+  const opts = typeof options === "string" ? {
+    name: options
+  } : options;
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(METADATA_KEYS.SUBCOMMAND, opts, target, propertyKey);
+  };
+}
+__name(SubCommand, "SubCommand");
+
 // src/decorators/utils.ts
-function buildSimpleCommandMetadata(options, methodName, category) {
+function buildSimpleCommandMetadata(options, methodName, category, params) {
   return {
     name: options.name ?? methodName.toLowerCase(),
     description: options.description ?? "No description provided",
@@ -173,11 +279,25 @@ function buildSimpleCommandMetadata(options, methodName, category) {
     } : {},
     nsfw: options.nsfw ?? false,
     ownerOnly: options.ownerOnly ?? false,
-    options: options.options ?? [],
-    args: options.args ?? []
+    params
   };
 }
 __name(buildSimpleCommandMetadata, "buildSimpleCommandMetadata");
+function getSubCommands(target) {
+  const methods = Object.getOwnPropertyNames(target.prototype);
+  const subCommands = [];
+  for (const method of methods) {
+    const options = Reflect.getMetadata(METADATA_KEYS.SUBCOMMAND, target.prototype, method);
+    if (options) {
+      subCommands.push({
+        methodName: method,
+        options
+      });
+    }
+  }
+  return subCommands;
+}
+__name(getSubCommands, "getSubCommands");
 
 // src/registry.ts
 import * as path from "path";
@@ -200,22 +320,18 @@ var CommandRegistry = class _CommandRegistry {
   registeredEvents = [];
   extensions;
   processedStoatClasses = /* @__PURE__ */ new Set();
-  constructor(extensions = [
+  container;
+  constructor(container, extensions = [
     ".js",
     ".mjs",
     ".cjs"
   ]) {
+    this.container = container;
     this.extensions = extensions;
   }
-  /**
-  * Get the number of registered commands
-  */
   get size() {
     return this.commands.size;
   }
-  /**
-  * 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) {
@@ -233,9 +349,6 @@ 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.
-  */
   async autoDiscover(options = {}) {
     const roots = options.roots?.length ? options.roots : [
       process.cwd()
@@ -252,12 +365,10 @@ var CommandRegistry = class _CommandRegistry {
     const uniqueFiles = [
       ...new Set(files)
     ];
-    let candidateFiles = 0;
     for (const file of uniqueFiles) {
       if (!await this.isLikelyCommandModule(file)) {
         continue;
       }
-      candidateFiles++;
       const baseDir = roots.find((root) => {
         const relative2 = path.relative(root, file);
         return relative2 && !relative2.startsWith("..") && !path.isAbsolute(relative2);
@@ -277,11 +388,11 @@ var CommandRegistry = class _CommandRegistry {
       return true;
     }
   }
-  /**
-  * Register a command instance
-  */
   register(instance, metadata, classConstructor, methodName) {
-    const name = metadata.name.toLowerCase();
+    const groupOptions = Reflect.getMetadata(METADATA_KEYS.COMMAND_GROUP, classConstructor);
+    const subCommandOptions = Reflect.getMetadata(METADATA_KEYS.SUBCOMMAND, instance, methodName);
+    const subCommandName = subCommandOptions?.name;
+    const name = groupOptions && subCommandName ? `${groupOptions.name}:${subCommandName}`.toLowerCase() : metadata.name.toLowerCase();
     if (this.commands.has(name)) {
       console.warn(`[Stoatx] Duplicate command name: ${name}. Skipping...`);
       return;
@@ -302,42 +413,24 @@ var CommandRegistry = class _CommandRegistry {
       this.aliases.set(aliasLower, name);
     }
   }
-  /**
-  * 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
-  */
   has(name) {
     const lowerName = name.toLowerCase();
     return this.commands.has(lowerName) || this.aliases.has(lowerName);
   }
-  /**
-  * Get all registered commands
-  */
   getAll() {
     return Array.from(this.commands.values());
   }
-  /**
-  * Get all command metadata
-  */
   getAllMetadata() {
     return this.getAll().map((c) => c.metadata);
   }
-  /**
-  * Get all registered events
-  */
   getEvents() {
     return this.registeredEvents;
   }
-  /**
-  * Get commands grouped by category
-  */
   getByCategory() {
     const categories = /* @__PURE__ */ new Map();
     for (const cmd of this.commands.values()) {
@@ -348,89 +441,70 @@ var CommandRegistry = class _CommandRegistry {
     }
     return categories;
   }
-  /**
-  * Clear all commands
-  */
   clear() {
     this.commands.clear();
     this.aliases.clear();
     this.registeredEvents.length = 0;
     this.processedStoatClasses.clear();
   }
-  /**
-  * Iterate over commands
-  */
   [Symbol.iterator]() {
     return this.commands.entries();
   }
-  /**
-  * Iterate over command values
-  */
   values() {
     return this.commands.values();
   }
-  /**
-  * 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
-  */
   validateGuards(commandClass, commandName) {
-    const guards = Reflect.getMetadata("stoatx:command:guards", commandClass) || [];
+    const guards = Reflect.getMetadata(METADATA_KEYS.GUARDS, commandClass) || [];
     for (const GuardClass of guards) {
-      const guardInstance = new GuardClass();
+      const guardInstance = this.container.resolve(GuardClass);
       if (typeof guardInstance.run !== "function") {
         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] All guards must implement guardFail() to handle failed checks.`);
         process.exit(1);
       }
     }
   }
-  /**
-  * Load commands from a single file
-  */
   async loadFile(filePath, baseDir) {
     try {
       const knownStoatClasses = new Set(decoratorStore.getStoatClasses().keys());
       const fileUrl = pathToFileURL(filePath).href;
       await import(fileUrl);
       const allStoatClasses = decoratorStore.getStoatClasses();
-      for (const [stoatClass, stoatInstance] of allStoatClasses.entries()) {
+      for (const [stoatClass] of allStoatClasses.entries()) {
         if (knownStoatClasses.has(stoatClass) || this.processedStoatClasses.has(stoatClass)) {
           continue;
         }
-        this.registerStoatClassCommands(stoatClass, stoatInstance, filePath, baseDir);
+        this.registerStoatClassCommands(stoatClass, filePath, baseDir);
       }
     } catch (error) {
       console.error(`[Stoatx] Failed to load command file: ${filePath}`, error);
     }
   }
-  registerStoatClassCommands(stoatClass, instance, filePath, baseDir) {
+  registerStoatClassCommands(stoatClass, filePath, baseDir) {
+    const instance = this.container.resolve(stoatClass);
     const simpleCommands = getSimpleCommands(stoatClass);
+    const subCommands = getSubCommands(stoatClass);
     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...`);
+    const allCommands = [
+      ...simpleCommands,
+      ...subCommands
+    ];
+    if (allCommands.length === 0 && events.length === 0) {
       this.processedStoatClasses.add(stoatClass);
       return;
     }
-    for (const cmdDef of simpleCommands) {
+    for (const cmdDef of allCommands) {
       const method = instance[cmdDef.methodName];
-      if (typeof method !== "function") {
-        console.warn(`[Stoatx] Method ${cmdDef.methodName} not found on ${stoatClass.name}. Skipping...`);
-        continue;
-      }
-      const metadata = buildSimpleCommandMetadata(cmdDef.options, cmdDef.methodName, category);
+      if (typeof method !== "function") continue;
+      const params = this.buildParamSchema(stoatClass.prototype, cmdDef.methodName);
+      const metadata = buildSimpleCommandMetadata(cmdDef.options, cmdDef.methodName, category, params);
       this.register(instance, metadata, stoatClass, cmdDef.methodName);
     }
     for (const eventDef of events) {
@@ -449,15 +523,60 @@ var CommandRegistry = class _CommandRegistry {
     this.processedStoatClasses.add(stoatClass);
   }
   /**
-  * Derive category from file path relative to base directory
+  * Build the parameter schema for a command method by combining
+  * reflect-metadata param types with @Arg/@Option decorator metadata.
   */
+  buildParamSchema(prototype, methodName) {
+    const paramTypes = Reflect.getMetadata("design:paramtypes", prototype, methodName) ?? [];
+    const argDefs = getArgs(prototype, methodName);
+    const optionDefs = getOptions(prototype, methodName);
+    const argByIndex = new Map(argDefs.map((a) => [
+      a.index,
+      a
+    ]));
+    const optionByIndex = new Map(optionDefs.map((o) => [
+      o.index,
+      o
+    ]));
+    const params = [];
+    for (let i = 0; i < paramTypes.length; i++) {
+      const reflectedType = paramTypes[i];
+      if (optionByIndex.has(i)) {
+        const optDef = optionByIndex.get(i);
+        const resolvedType = reflectedType ? PARAM_TYPE_MAP.get(reflectedType) ?? "string" : "string";
+        params.push({
+          index: i,
+          kind: "option",
+          resolvedType,
+          name: optDef.name,
+          required: optDef.required
+        });
+        continue;
+      }
+      if (argByIndex.has(i)) {
+        const argDef = argByIndex.get(i);
+        const resolvedType = reflectedType ? PARAM_TYPE_MAP.get(reflectedType) ?? "string" : "string";
+        params.push({
+          index: i,
+          kind: "arg",
+          resolvedType,
+          required: argDef.required,
+          fetch: argDef.fetch
+        });
+        continue;
+      }
+      params.push({
+        index: i,
+        kind: "ctx",
+        resolvedType: "ctx"
+      });
+    }
+    return params;
+  }
   getCategoryFromPath(filePath, baseDir) {
     const relative2 = path.relative(baseDir, filePath);
     const parts = relative2.split(path.sep);
-    if (parts.length > 1) {
-      return parts[0];
-    }
-    return void 0;
+    return parts.length > 1 ? parts[0] : void 0;
   }
 };
 
@@ -465,16 +584,113 @@ var CommandRegistry = class _CommandRegistry {
 import "reflect-metadata";
 
 // src/error.ts
-var CommandValidationError = class extends Error {
+var StoatxError = class extends Error {
+  static {
+    __name(this, "StoatxError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "StoatxError";
+  }
+};
+var CommandValidationError = class extends StoatxError {
   static {
     __name(this, "CommandValidationError");
   }
-  optionName;
-  constructor(optionName, message) {
-    super(message), this.optionName = optionName;
+  paramName;
+  paramKind;
+  constructor(paramName, paramKind, message) {
+    super(message), this.paramName = paramName, this.paramKind = paramKind;
     this.name = "CommandValidationError";
   }
 };
+var MissingArgumentError = class extends CommandValidationError {
+  static {
+    __name(this, "MissingArgumentError");
+  }
+  constructor(paramName) {
+    super(paramName, "arg", `Missing required argument: \`<${paramName}>\``);
+    this.name = "MissingArgumentError";
+  }
+};
+var MissingOptionError = class extends CommandValidationError {
+  static {
+    __name(this, "MissingOptionError");
+  }
+  constructor(paramName, flagPrefix) {
+    super(paramName, "option", `Missing required option: \`${flagPrefix.repeat(2)}${paramName}\``);
+    this.name = "MissingOptionError";
+  }
+};
+var InvalidTypeError = class extends CommandValidationError {
+  static {
+    __name(this, "InvalidTypeError");
+  }
+  expected;
+  received;
+  constructor(paramName, paramKind, expected, received) {
+    super(paramName, paramKind, `Invalid value for \`${paramName}\`. Expected ${expected}, got \`${received}\`.`), this.expected = expected, this.received = received;
+    this.name = "InvalidTypeError";
+  }
+};
+var InvalidMentionError = class extends CommandValidationError {
+  static {
+    __name(this, "InvalidMentionError");
+  }
+  mentionKind;
+  rawValue;
+  constructor(paramName, paramKind, mentionKind, rawValue) {
+    super(paramName, paramKind, `Invalid ${mentionKind} mention for \`${paramName}\`.`), this.mentionKind = mentionKind, this.rawValue = rawValue;
+    this.name = "InvalidMentionError";
+  }
+};
+var FetchFailedError = class extends CommandValidationError {
+  static {
+    __name(this, "FetchFailedError");
+  }
+  mentionKind;
+  resolvedId;
+  constructor(paramName, paramKind, mentionKind, resolvedId) {
+    super(paramName, paramKind, `Could not fetch ${mentionKind} \`${resolvedId}\` for \`${paramName}\`.`), this.mentionKind = mentionKind, this.resolvedId = resolvedId;
+    this.name = "FetchFailedError";
+  }
+};
+var NoServerContextError = class extends CommandValidationError {
+  static {
+    __name(this, "NoServerContextError");
+  }
+  constructor(paramName, paramKind) {
+    super(paramName, paramKind, `Cannot fetch role for \`${paramName}\` outside of a server.`);
+    this.name = "NoServerContextError";
+  }
+};
+
+// src/di/Container.ts
+import "reflect-metadata";
+var StoatxContainer = class {
+  static {
+    __name(this, "StoatxContainer");
+  }
+  instances = /* @__PURE__ */ new Map();
+  /**
+  * Resolves a class instance, injecting any required dependencies.
+  */
+  resolve(target) {
+    if (this.instances.has(target)) {
+      return this.instances.get(target);
+    }
+    const paramTypes = Reflect.getMetadata("design:paramtypes", target) || [];
+    const injections = paramTypes.map((param) => {
+      if (!param) {
+        throw new Error(`[Stoatx DI] Cannot resolve dependency for ${target.name}. Ensure all injected services are decorated with @Injectable().`);
+      }
+      return this.resolve(param);
+    });
+    const instance = new target(...injections);
+    this.instances.set(target, instance);
+    return instance;
+  }
+};
 
 // src/handler.ts
 var DefaultCooldownManager = class {
@@ -518,6 +734,7 @@ var StoatxHandler = class {
   }
   commandsDir;
   discoveryOptions;
+  // After
   prefixResolver;
   owners;
   registry;
@@ -525,20 +742,20 @@ var StoatxHandler = class {
   disableMentionPrefix;
   client;
   flagPrefix;
+  globalGuards;
+  container = new StoatxContainer();
   constructor(options) {
     this.client = options.client;
     this.commandsDir = options.commandsDir;
     this.discoveryOptions = options.discovery;
     this.prefixResolver = options.prefix;
     this.owners = new Set(options.owners ?? []);
-    this.registry = new CommandRegistry(options.extensions);
+    this.registry = new CommandRegistry(this.container, options.extensions);
     this.disableMentionPrefix = options.disableMentionPrefix ?? false;
     this.cooldownManager = options.cooldownManager ?? new DefaultCooldownManager();
     this.flagPrefix = options.flagPrefix || "-";
+    this.globalGuards = options.globalGuards ?? [];
   }
-  /**
-  * Initialize the handler - load all commands
-  */
   async init() {
     if (this.commandsDir) {
       await this.registry.loadFromDirectory(this.commandsDir);
@@ -547,9 +764,6 @@ var StoatxHandler = class {
     }
     this.attachEvents();
   }
-  /**
-  * Attach registered events to the client
-  */
   attachEvents() {
     const events = this.registry.getEvents();
     for (const eventDef of events) {
@@ -568,12 +782,9 @@ var StoatxHandler = class {
       }
     }
   }
-  /**
-  * Parses raw string arguments into positional args and key-value options
-  */
-  parseCommandOptions(rawArgs) {
+  parseRawInput(rawArgs) {
     const args = [];
-    const options = {};
+    const flags = {};
     for (let i = 0; i < rawArgs.length; i++) {
       const arg = rawArgs[i];
       if (arg === void 0) continue;
@@ -584,10 +795,10 @@ var StoatxHandler = class {
         }
         const nextArg = rawArgs[i + 1];
         if (nextArg !== void 0 && !nextArg.startsWith(this.flagPrefix)) {
-          options[key] = nextArg;
+          flags[key] = nextArg;
           i++;
         } else {
-          options[key] = true;
+          flags[key] = true;
         }
       } else {
         args.push(arg);
@@ -595,78 +806,62 @@ var StoatxHandler = class {
     }
     return {
       args,
-      options
+      flags
     };
   }
-  /**
-  * Parse a raw message into command context
-  */
   async parseMessage(rawContent, message, meta) {
-    const prefix = await this.resolvePrefix(meta.serverId);
-    let usedPrefix = prefix;
+    const prefixes = await this.resolvePrefix(meta.serverId);
+    let usedPrefix = "";
     let withoutPrefix = "";
-    if (rawContent.startsWith(prefix)) {
-      withoutPrefix = rawContent.slice(prefix.length).trim();
-      usedPrefix = prefix;
-    } else if (!this.disableMentionPrefix && rawContent.match(/^<@!?[\w]+>/)) {
-      const mentionMatch = rawContent.match(/^<@!?([\w]+)>\s*/);
+    const matchedPrefix = prefixes.find((p) => rawContent.startsWith(p));
+    if (matchedPrefix !== void 0) {
+      usedPrefix = matchedPrefix;
+      withoutPrefix = rawContent.slice(matchedPrefix.length).trim();
+    } else if (!this.disableMentionPrefix && rawContent.match(/^<@!?\w+>/)) {
+      const mentionMatch = rawContent.match(/^<@!?(\w+)>\s*/);
       if (mentionMatch) {
         const mentionedId = mentionMatch[1];
         const botId = this.client.user?.id;
         if (botId && mentionedId === botId) {
           usedPrefix = mentionMatch[0];
           withoutPrefix = rawContent.slice(mentionMatch[0].length).trim();
-        } else {
         }
       }
     }
-    if (!withoutPrefix) {
-      return null;
-    }
-    const [commandName, ...rawArgs] = withoutPrefix.split(/\s+/);
-    if (!commandName) {
-      return null;
+    if (!withoutPrefix) return null;
+    const parts = withoutPrefix.split(/\s+/);
+    const part1 = parts[0];
+    const part2 = parts[1];
+    if (!part1) return null;
+    let commandKey = part1.toLowerCase();
+    let remainingParts = parts.slice(1);
+    if (part2 && this.registry.has(`${part1}:${part2}`)) {
+      commandKey = `${part1}:${part2}`.toLowerCase();
+      remainingParts = parts.slice(2);
     }
-    const { args, options } = this.parseCommandOptions(rawArgs);
+    const { args, flags } = this.parseRawInput(remainingParts);
     return {
       client: this.client,
       content: rawContent,
       authorId: meta.authorId,
       channelId: meta.channelId,
       serverId: meta.serverId,
-      args,
-      options,
       prefix: usedPrefix,
-      commandName: commandName.toLowerCase(),
+      commandName: commandKey,
       reply: meta.reply,
-      message
+      message,
+      _rawArgs: args,
+      _rawFlags: flags
     };
   }
-  /**
-  * 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;
-    }
-    if (message.author.bot) {
-      return false;
-    }
+    if (!message.channel || !message.author || !message.content) return false;
+    if (message.author.bot) return false;
     const rawContent = message.content;
     const authorId = message.author.id;
     const channelId = message.channel.id;
     const serverId = message.server?.id;
-    const reply = /* @__PURE__ */ __name(async (content) => {
-      return await message.channel.send(content);
-    }, "reply");
+    const reply = /* @__PURE__ */ __name(async (content) => await message.channel.send(content), "reply");
     await this.handleMessage(rawContent, message, {
       authorId,
       channelId,
@@ -675,44 +870,20 @@ 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),
-  *   });
-  * });
-  * ```
-  */
   async handleMessage(rawContent, message, meta) {
     const ctx = await this.parseMessage(rawContent, message, meta);
-    if (!ctx) {
-      return;
-    }
+    if (!ctx) return;
     await this.execute(ctx);
   }
-  /**
-  * Execute a command with the given context
-  */
   async execute(ctx) {
     const registered = this.registry.get(ctx.commandName);
-    if (!registered) {
-      return false;
-    }
+    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;
     }
-    if (metadata.permissions) {
+    if (metadata.permissions.length > 0) {
       const server = ctx.message.server;
       const member = server ? await server.members.fetch(ctx.authorId) : null;
       if (!member || !member.permissions.has(metadata.permissions)) {
@@ -725,9 +896,16 @@ var StoatxHandler = class {
         return false;
       }
     }
-    const guards = Reflect.getMetadata("stoatx:command:guards", classConstructor) || [];
-    for (const guardClass of guards) {
-      const guardInstance = new guardClass();
+    const globalGuards = this.globalGuards;
+    const classGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, classConstructor) || [];
+    const methodGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, instance, methodName) || [];
+    const allGuards = [
+      ...globalGuards,
+      ...classGuards,
+      ...methodGuards
+    ];
+    for (const guardClass of allGuards) {
+      const guardInstance = this.container.resolve(guardClass);
       if (typeof guardInstance.run === "function") {
         const guardResult = await guardInstance.run(ctx);
         if (!guardResult) {
@@ -740,190 +918,6 @@ 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") {
@@ -933,42 +927,152 @@ var StoatxHandler = class {
       }
       return false;
     }
+    const resolvedParams = await this.resolveParams(metadata.params, ctx, instance);
+    if (resolvedParams === null) return false;
     try {
       if (metadata.cooldown > 0) {
         await this.cooldownManager.set(ctx, metadata);
       }
-      await instance[methodName](ctx);
+      await instance[methodName](...resolvedParams);
       return true;
     } catch (error) {
       if (typeof instance.onError === "function") {
         await instance.onError(ctx, error);
       } else {
         console.error(`[Stoatx] Error in command ${metadata.name}:`, error);
+        await ctx.reply("Something went wrong. Please try again later.");
       }
       return false;
     }
   }
   /**
-  * Get the command registry
+  * Report a validation error to the instance via onValidationError → onError → default reply
   */
+  async reportValidationError(instance, ctx, error) {
+    if (typeof instance.onValidationError === "function") {
+      await instance.onValidationError(ctx, error);
+    } else if (typeof instance.onError === "function") {
+      await instance.onError(ctx, error);
+    } else {
+      await ctx.reply(error.message);
+    }
+    return null;
+  }
+  async resolveParams(params, ctx, instance) {
+    const resolved = new Array(params.length);
+    let argCursor = 0;
+    for (const param of params) {
+      if (param.kind === "ctx") {
+        resolved[param.index] = ctx;
+        continue;
+      }
+      if (param.kind === "arg") {
+        const rawValue = ctx._rawArgs[argCursor++];
+        if (rawValue === void 0) {
+          if (param.required) {
+            const paramName = param.name ?? `arg[${param.index}]`;
+            return this.reportValidationError(instance, ctx, new MissingArgumentError(paramName));
+          }
+          resolved[param.index] = void 0;
+          continue;
+        }
+        const value = await this.resolveValue(rawValue, param, ctx, instance, "arg");
+        if (value === null) return null;
+        resolved[param.index] = value;
+        continue;
+      }
+      if (param.kind === "option") {
+        const rawValue = ctx._rawFlags[param.name];
+        if (rawValue === void 0) {
+          if (param.required) {
+            return this.reportValidationError(instance, ctx, new MissingOptionError(param.name, this.flagPrefix));
+          }
+          resolved[param.index] = void 0;
+          continue;
+        }
+        const value = await this.resolveValue(String(rawValue), param, ctx, instance, "option");
+        if (value === null) return null;
+        resolved[param.index] = value;
+      }
+    }
+    return resolved;
+  }
+  async resolveValue(rawValue, param, ctx, instance, kind) {
+    const paramName = kind === "arg" ? param.name ?? `arg[${param.index}]` : param.name;
+    switch (param.resolvedType) {
+      case "string":
+        return String(rawValue);
+      case "number": {
+        const num = Number(rawValue);
+        if (isNaN(num)) {
+          return this.reportValidationError(instance, ctx, new InvalidTypeError(paramName, kind, "a number", rawValue));
+        }
+        return num;
+      }
+      case "boolean":
+        return rawValue === "false" ? false : Boolean(rawValue);
+      case "user": {
+        const match = rawValue.match(/^(?:<@!?)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+        if (!match) {
+          return this.reportValidationError(instance, ctx, new InvalidMentionError(paramName, kind, "user", rawValue));
+        }
+        const userId = match[1];
+        if (param.fetch) {
+          try {
+            return await this.client.users.fetch(userId);
+          } catch {
+            return this.reportValidationError(instance, ctx, new FetchFailedError(paramName, kind, "user", userId));
+          }
+        }
+        return this.client.users.cache.get(userId) ?? userId;
+      }
+      case "channel": {
+        const match = rawValue.match(/^(?:<#)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+        if (!match) {
+          return this.reportValidationError(instance, ctx, new InvalidMentionError(paramName, kind, "channel", rawValue));
+        }
+        const channelId = match[1];
+        if (param.fetch) {
+          try {
+            return await this.client.channels.fetch(channelId);
+          } catch {
+            return this.reportValidationError(instance, ctx, new FetchFailedError(paramName, kind, "channel", channelId));
+          }
+        }
+        return this.client.channels.cache.get(channelId) ?? channelId;
+      }
+      case "role": {
+        const match = rawValue.match(/^(?:<@&)?([0-7][0-9A-HJKMNP-TV-Z]{25})>?$/i);
+        if (!match) {
+          return this.reportValidationError(instance, ctx, new InvalidMentionError(paramName, kind, "role", rawValue));
+        }
+        const roleId = match[1];
+        if (param.fetch) {
+          const server = ctx.message.server;
+          if (!server) {
+            return this.reportValidationError(instance, ctx, new NoServerContextError(paramName, kind));
+          }
+          try {
+            return await server.roles.fetch(roleId);
+          } catch {
+            return this.reportValidationError(instance, ctx, new FetchFailedError(paramName, kind, "role", roleId));
+          }
+        }
+        return ctx.message.server?.roles.cache.get(roleId) ?? roleId;
+      }
+      default:
+        return rawValue;
+    }
+  }
   getRegistry() {
     return this.registry;
   }
-  /**
-  * Get a command by name or alias
-  */
   getCommand(name) {
     return this.registry.get(name);
   }
-  /**
-  * Get all commands
-  */
   getCommands() {
     return this.registry.getAll();
   }
-  /**
-  * Reload all commands
-  */
   async reload() {
     this.registry.clear();
     if (this.cooldownManager.clear) {
@@ -980,34 +1084,22 @@ var StoatxHandler = class {
     }
     await this.registry.autoDiscover(this.discoveryOptions);
   }
-  /**
-  * Check if a user is an owner
-  */
   isOwner(userId) {
     return this.owners.has(userId);
   }
-  /**
-  * Add an owner
-  */
   addOwner(userId) {
     this.owners.add(userId);
   }
-  /**
-  * Remove an owner
-  */
   removeOwner(userId) {
     this.owners.delete(userId);
   }
-  /**
-  * Resolve the prefix for a context
-  */
   async resolvePrefix(serverId) {
-    if (typeof this.prefixResolver === "function") {
-      return this.prefixResolver({
-        serverId
-      });
-    }
-    return this.prefixResolver;
+    const result = typeof this.prefixResolver === "function" ? await this.prefixResolver({
+      serverId
+    }) : this.prefixResolver;
+    return Array.isArray(result) ? result : [
+      result
+    ];
   }
 };
 
@@ -1037,16 +1129,29 @@ var Client = class extends StoatClient {
 // src/index.ts
 export * from "@stoatx/client";
 export {
+  Arg,
   Client,
+  CommandGroup,
   CommandRegistry,
   CommandValidationError,
   DefaultCooldownManager,
+  FetchFailedError,
   Guard,
+  Injectable,
+  InvalidMentionError,
+  InvalidTypeError,
   METADATA_KEYS,
+  MissingArgumentError,
+  MissingOptionError,
+  NoServerContextError,
   On,
   Once,
+  Option,
+  PARAM_TYPE_MAP,
   SimpleCommand,
   Stoat,
+  StoatxError,
+  SubCommand,
   buildSimpleCommandMetadata,
   getEventsMetadata,
   getGuards,