stoatx 0.7.7 → 1.0.1

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 });
@@ -31,15 +32,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Arg: () => Arg,
   Client: () => Client,
+  CommandGroup: () => CommandGroup,
   CommandRegistry: () => CommandRegistry,
+  CommandValidationError: () => CommandValidationError,
   DefaultCooldownManager: () => DefaultCooldownManager,
+  FetchFailedError: () => FetchFailedError,
   Guard: () => Guard,
+  Injectable: () => Injectable,
+  InvalidMentionError: () => InvalidMentionError,
+  InvalidTypeError: () => InvalidTypeError,
   METADATA_KEYS: () => METADATA_KEYS,
+  MissingArgumentError: () => MissingArgumentError,
+  MissingOptionError: () => MissingOptionError,
+  NoServerContextError: () => NoServerContextError,
   On: () => On,
   Once: () => Once,
+  Option: () => Option,
+  PARAM_TYPE_MAP: () => PARAM_TYPE_MAP,
   SimpleCommand: () => SimpleCommand,
   Stoat: () => Stoat,
+  StoatxError: () => StoatxError,
+  SubCommand: () => SubCommand,
   buildSimpleCommandMetadata: () => buildSimpleCommandMetadata,
   getEventsMetadata: () => getEventsMetadata,
   getGuards: () => getGuards,
@@ -48,6 +63,35 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types.ts
+var import_client = require("@stoatx/client");
+var PARAM_TYPE_MAP = /* @__PURE__ */ new Map([
+  [
+    String,
+    "string"
+  ],
+  [
+    Number,
+    "number"
+  ],
+  [
+    Boolean,
+    "boolean"
+  ],
+  [
+    import_client.User,
+    "user"
+  ],
+  [
+    import_client.BaseChannel,
+    "channel"
+  ],
+  [
+    import_client.Role,
+    "role"
+  ]
+]);
+
 // src/decorators/Stoat.ts
 var import_reflect_metadata = require("reflect-metadata");
 
@@ -56,14 +100,22 @@ 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
 var DecoratorStore = class _DecoratorStore {
+  static {
+    __name(this, "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 */
@@ -77,49 +129,46 @@ 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();
-      this.stoatClasses.set(classConstructor, instance);
-    }
+    this.stoatClasses.add(classConstructor);
   }
   /**
-   * 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 +182,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,22 +202,35 @@ 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");
 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);
+    }
   };
 }
-function getGuards(target) {
+__name(Guard, "Guard");
+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");
 
 // src/decorators/Events.ts
 var import_reflect_metadata4 = require("reflect-metadata");
@@ -183,18 +247,88 @@ 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/Arg.ts
+var import_reflect_metadata5 = require("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
+var import_reflect_metadata6 = require("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
+var import_reflect_metadata7 = require("reflect-metadata");
+function Injectable() {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.INJECTABLE, true, target);
+  };
+}
+__name(Injectable, "Injectable");
+
+// src/decorators/CommandGroup.ts
+var import_reflect_metadata8 = require("reflect-metadata");
+function CommandGroup(name) {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.COMMAND_GROUP, name, target);
+  };
+}
+__name(CommandGroup, "CommandGroup");
+
+// src/decorators/SubCommand.ts
+var import_reflect_metadata9 = require("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",
@@ -202,11 +336,30 @@ 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,
+    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
 var path = __toESM(require("path"));
@@ -214,6 +367,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 +382,27 @@ var CommandRegistry = class _CommandRegistry {
   registeredEvents = [];
   extensions;
   processedStoatClasses = /* @__PURE__ */ new Set();
-  constructor(extensions = [".js", ".mjs", ".cjs"]) {
+  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) {
       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) {
@@ -251,26 +411,26 @@ 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()];
+    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)];
-    let candidateFiles = 0;
+    const uniqueFiles = [
+      ...new Set(files)
+    ];
     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);
@@ -290,17 +450,22 @@ 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;
     }
     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)) {
@@ -310,42 +475,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()) {
@@ -356,95 +503,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.`
-        );
+        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.`);
+        console.error(`[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`);
         process.exit(1);
       }
     }
   }
-  /**
-   * Load commands from a single file
-   */
   async loadFile(filePath, baseDir) {
     try {
       const knownStoatClasses = new Set(decoratorStore.getStoatClasses().keys());
       const fileUrl = (0, import_node_url.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) {
@@ -463,21 +585,180 @@ 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 parts.length > 1 ? parts[0] : void 0;
+  }
+};
+
+// src/handler.ts
+var import_reflect_metadata11 = require("reflect-metadata");
+
+// src/error.ts
+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");
+  }
+  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
+var import_reflect_metadata10 = require("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);
     }
-    return void 0;
+    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 import_reflect_metadata5 = require("reflect-metadata");
 var DefaultCooldownManager = class {
+  static {
+    __name(this, "DefaultCooldownManager");
+  }
   cooldowns = /* @__PURE__ */ new Map();
   check(ctx, metadata) {
     if (metadata.cooldown <= 0) return true;
@@ -510,27 +791,33 @@ var DefaultCooldownManager = class {
   }
 };
 var StoatxHandler = class {
+  static {
+    __name(this, "StoatxHandler");
+  }
   commandsDir;
   discoveryOptions;
+  // After
   prefixResolver;
   owners;
   registry;
   cooldownManager;
   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);
@@ -539,22 +826,16 @@ var StoatxHandler = class {
     }
     this.attachEvents();
   }
-  /**
-   * 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);
@@ -563,73 +844,86 @@ var StoatxHandler = class {
       }
     }
   }
-  /**
-   * Parse a raw message into command context
-   */
+  parseRawInput(rawArgs) {
+    const args = [];
+    const flags = {};
+    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)) {
+          flags[key] = nextArg;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      } else {
+        args.push(arg);
+      }
+    }
+    return {
+      args,
+      flags
+    };
+  }
   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, ...args] = 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, flags } = this.parseRawInput(remainingParts);
     return {
       client: this.client,
       content: rawContent,
       authorId: meta.authorId,
       channelId: meta.channelId,
       serverId: meta.serverId,
-      args,
       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 = async (content) => {
-      return await message.channel.send(content);
-    };
+    const reply = /* @__PURE__ */ __name(async (content) => await message.channel.send(content), "reply");
     await this.handleMessage(rawContent, message, {
       authorId,
       channelId,
@@ -638,43 +932,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;
     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)) {
@@ -687,9 +958,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) {
@@ -711,42 +989,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) {
@@ -758,48 +1146,45 @@ 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
+    ];
   }
 };
 
 // src/client.ts
-var import_client = require("@stoatx/client");
-var Client = class extends import_client.Client {
+var import_client2 = require("@stoatx/client");
+var Client = class extends import_client2.Client {
+  static {
+    __name(this, "Client");
+  }
   handler;
   constructor(options) {
-    super();
-    this.handler = new StoatxHandler({ ...options, client: this });
-    this.on("messageCreate", async (message) => {
-      await this.handler.handle(message);
+    super(options);
+    this.handler = new StoatxHandler({
+      ...options,
+      client: this
     });
   }
-  async initCommands() {
+  async login(token) {
     await this.handler.init();
+    return super.login(token);
+  }
+  async executeCommand(message) {
+    await this.handler.handle(message);
   }
 };
 
@@ -807,15 +1192,29 @@ var Client = class extends import_client.Client {
 __reExport(index_exports, require("@stoatx/client"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  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,