stoatx 0.8.0 → 1.0.1

package/dist/index.d.mts

@@ -1,45 +1,31 @@
-import { Message, Client as Client$1, ClientOptions, PermissionResolvable } from '@stoatx/client';
+import { Message, Client as Client$1, ClientOptions, PermissionResolvable, ClientEvents } from '@stoatx/client';
 export * from '@stoatx/client';
 
+declare class StoatxContainer {
+    private instances;
+    /**
+     * Resolves a class instance, injecting any required dependencies.
+     */
+    resolve<T>(target: any): T;
+}
+
 interface AutoDiscoveryOptions {
     roots?: string[];
     include?: string[];
     ignore?: string[];
 }
-/**
- * Stored command entry from @Stoat/@SimpleCommand registration.
- */
 interface RegisteredCommand {
-    /** Instance of the @Stoat class */
     instance: object;
-    /** Command metadata */
     metadata: CommandMetadata;
-    /** Method name to call */
     methodName: string;
-    /** The original class constructor (for guard validation) */
     classConstructor: Function;
 }
-/**
- * Stored event entry from @On/@Once registration.
- */
 interface RegisteredEvent {
     instance: object;
     methodName: string;
     event: string;
     type: "on" | "once";
 }
-/**
- * CommandRegistry - Scans directories and stores commands in a Map
- *
- * @example
- * ```ts
- * const registry = new CommandRegistry();
- * await registry.loadFromDirectory('./src/commands');
- *
- * const ping = registry.get('ping');
- * const allCommands = registry.getAll();
- * ```
- */
 declare class CommandRegistry {
     private static readonly DEFAULT_AUTO_DISCOVERY_IGNORES;
     private readonly commands;
@@ -47,80 +33,32 @@ declare class CommandRegistry {
     private readonly registeredEvents;
     private readonly extensions;
     private readonly processedStoatClasses;
-    constructor(extensions?: string[]);
-    /**
-     * Get the number of registered commands
-     */
+    private readonly container;
+    constructor(container: StoatxContainer, extensions?: string[]);
     get size(): number;
-    /**
-     * Load commands from a directory using glob pattern matching
-     */
     loadFromDirectory(directory: string): Promise<void>;
-    /**
-     * Auto-discover command files across one or more roots.
-     */
     autoDiscover(options?: AutoDiscoveryOptions): Promise<void>;
     private getDefaultAutoDiscoveryPatterns;
     private isLikelyCommandModule;
-    /**
-     * Register a command instance
-     */
     register(instance: object, metadata: CommandMetadata, classConstructor: Function, methodName: string): void;
-    /**
-     * Get a command by name or alias
-     */
     get(name: string): RegisteredCommand | undefined;
-    /**
-     * Check if a command exists
-     */
     has(name: string): boolean;
-    /**
-     * Get all registered commands
-     */
     getAll(): RegisteredCommand[];
-    /**
-     * Get all command metadata
-     */
     getAllMetadata(): CommandMetadata[];
-    /**
-     * Get all registered events
-     */
     getEvents(): RegisteredEvent[];
-    /**
-     * Get commands grouped by category
-     */
     getByCategory(): Map<string, RegisteredCommand[]>;
-    /**
-     * Clear all commands
-     */
     clear(): void;
-    /**
-     * Iterate over commands
-     */
     [Symbol.iterator](): IterableIterator<[string, RegisteredCommand]>;
-    /**
-     * Iterate over command values
-     */
     values(): IterableIterator<RegisteredCommand>;
-    /**
-     * Iterate over command names
-     */
     keys(): IterableIterator<string>;
-    /**
-     * Validate that all guards on a command implement the required methods
-     * @param commandClass
-     * @param commandName
-     * @private
-     */
     private validateGuards;
-    /**
-     * Load commands from a single file
-     */
     private loadFile;
     private registerStoatClassCommands;
     /**
-     * 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.
      */
+    private buildParamSchema;
     private getCategoryFromPath;
 }
 
@@ -136,10 +74,7 @@ declare class DefaultCooldownManager implements CooldownManager {
 }
 /**
  * StoatxHandler - The execution engine for commands
- *
- * Handles message parsing, middleware execution, and command dispatching
- *
- * @internal This class is not intended to be instantiated directly. Use the `Client` from `stoatx` instead.
+ * @internal
  */
 declare class StoatxHandler {
     private readonly commandsDir;
@@ -151,97 +86,45 @@ declare class StoatxHandler {
     private readonly disableMentionPrefix;
     private readonly client;
     private readonly flagPrefix;
+    private readonly globalGuards;
+    readonly container: StoatxContainer;
     constructor(options: StoatxHandlerOptions);
-    /**
-     * Initialize the handler - load all commands
-     */
     init(): Promise<void>;
-    /**
-     * Attach registered events to the client
-     */
     private attachEvents;
-    /**
-     * Parses raw string arguments into positional args and key-value options
-     */
-    private parseCommandOptions;
-    /**
-     * Parse a raw message into command context
-     */
+    private parseRawInput;
     parseMessage(rawContent: string, message: Message, meta: {
         authorId: string;
         channelId: string;
         serverId?: string | undefined;
         reply: (content: string) => Promise<Message>;
-    }): Promise<CommandContext | null>;
-    /**
-     * Handle a message object using the configured message adapter
-     *
-     * @example
-     * ```ts
-     * // With message adapter configured
-     * client.on('messageCreate', (message) => {
-     *   handler.handle(message);
-     * });
-     * ```
-     */
+    }): Promise<(CommandContext & {
+        _rawArgs: string[];
+        _rawFlags: Record<string, string | boolean>;
+    }) | null>;
     handle(message: Message): Promise<boolean>;
-    /**
-     * 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),
-     *   });
-     * });
-     * ```
-     */
     handleMessage(rawContent: string, message: Message, meta: {
         authorId: string;
         channelId: string;
         serverId?: string | undefined;
         reply: (content: string) => Promise<Message>;
     }): Promise<void>;
+    execute(ctx: CommandContext & {
+        _rawArgs: string[];
+        _rawFlags: Record<string, string | boolean>;
+    }): Promise<boolean>;
     /**
-     * Execute a command with the given context
-     */
-    execute(ctx: CommandContext): Promise<boolean>;
-    /**
-     * Get the command registry
+     * Report a validation error to the instance via onValidationError → onError → default reply
      */
+    private reportValidationError;
+    private resolveParams;
+    private resolveValue;
     getRegistry(): CommandRegistry;
-    /**
-     * Get a command by name or alias
-     */
     getCommand(name: string): RegisteredCommand | undefined;
-    /**
-     * Get all commands
-     */
     getCommands(): RegisteredCommand[];
-    /**
-     * Reload all commands
-     */
     reload(): Promise<void>;
-    /**
-     * Check if a user is an owner
-     */
     isOwner(userId: string): boolean;
-    /**
-     * Add an owner
-     */
     addOwner(userId: string): void;
-    /**
-     * Remove an owner
-     */
     removeOwner(userId: string): void;
-    /**
-     * Resolve the prefix for a context
-     */
     private resolvePrefix;
 }
 
@@ -267,20 +150,81 @@ declare class Client extends Client$1 {
     executeCommand(message: Message): Promise<void>;
 }
 
-type OptionType = "string" | "number" | "boolean" | "user" | "channel" | "role";
-interface CommandOptionDefinition {
-    /** The name of the flag (e.g., "deleteMessages") */
-    name: string;
-    /** The expected data type */
-    type: OptionType;
-    /** Whether the user MUST provide this flag */
-    required?: boolean;
-    /** Description for help menus */
-    description?: string;
+/**
+ * Base error class for all Stoatx errors
+ */
+declare class StoatxError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for all command validation errors.
+ * Thrown before the command body runs when user input fails validation.
+ */
+declare class CommandValidationError extends StoatxError {
+    readonly paramName: string;
+    readonly paramKind: "arg" | "option";
+    constructor(paramName: string, paramKind: "arg" | "option", message: string);
+}
+/**
+ * Thrown when a required positional argument is missing
+ */
+declare class MissingArgumentError extends CommandValidationError {
+    constructor(paramName: string);
+}
+/**
+ * Thrown when a required named option is missing
+ */
+declare class MissingOptionError extends CommandValidationError {
+    constructor(paramName: string, flagPrefix: string);
+}
+/**
+ * Thrown when a value cannot be cast to the expected type
+ */
+declare class InvalidTypeError extends CommandValidationError {
+    readonly expected: string;
+    readonly received: string;
+    constructor(paramName: string, paramKind: "arg" | "option", expected: string, received: string);
+}
+/**
+ * Thrown when a mention string cannot be parsed as a valid ULID
+ */
+declare class InvalidMentionError extends CommandValidationError {
+    readonly mentionKind: "user" | "channel" | "role";
+    readonly rawValue: string;
+    constructor(paramName: string, paramKind: "arg" | "option", mentionKind: "user" | "channel" | "role", rawValue: string);
+}
+/**
+ * Thrown when fetch: true is set but the API call fails
+ */
+declare class FetchFailedError extends CommandValidationError {
+    readonly mentionKind: "user" | "channel" | "role";
+    readonly resolvedId: string;
+    constructor(paramName: string, paramKind: "arg" | "option", mentionKind: "user" | "channel" | "role", resolvedId: string);
+}
+/**
+ * Thrown when a role fetch is attempted outside a server context
+ */
+declare class NoServerContextError extends CommandValidationError {
+    constructor(paramName: string, paramKind: "arg" | "option");
+}
+
+/**
+ * Resolved parameter type from reflect-metadata or explicit decorator config
+ */
+type ResolvedParamType = "string" | "number" | "boolean" | "user" | "channel" | "role" | "ctx";
+/**
+ * Schema for a single method parameter decorated with @Arg, @Option, or inferred as ctx
+ */
+interface ParamSchema {
+    index: number;
+    kind: "arg" | "option" | "ctx";
+    resolvedType: ResolvedParamType;
+    name?: string;
+    required?: boolean | undefined;
+    fetch?: boolean | undefined;
 }
 /**
  * Simple command options passed to @SimpleCommand decorator
- * Used with @Stoat() decorated classes for method-based commands
  */
 interface SimpleCommandOptions {
     /** Command name (defaults to method name) */
@@ -301,10 +245,14 @@ interface SimpleCommandOptions {
     nsfw?: boolean;
     /** Whether the command is owner only */
     ownerOnly?: boolean;
-    /** Command options/flags (e.g., --deleteMessages true) */
-    options?: CommandOptionDefinition[];
-    /** Command args that act like flags without passing flags */
-    args?: CommandOptionDefinition[];
+}
+interface GroupOptions {
+    name: string;
+    description?: string;
+    permissions?: PermissionResolvable[];
+    ownerOnly?: boolean;
+    cooldown?: number;
+    nsfw?: boolean;
 }
 /**
  * Resolved command metadata with required fields
@@ -319,13 +267,14 @@ interface CommandMetadata {
     cooldownStorage?: string;
     nsfw: boolean;
     ownerOnly: boolean;
-    options?: CommandOptionDefinition[];
-    args?: CommandOptionDefinition[];
+    /** Parameter schema built at scan time from @Arg/@Option decorators */
+    params: ParamSchema[];
 }
 /**
- * Command execution context
+ * Command execution context — carries message context only.
+ * Args and options are injected directly as typed method parameters.
  */
-interface CommandContext<TOptions = Record<string, string | number | boolean>, TArgs extends (string | number | boolean)[] = (string | number | boolean)[], TClient extends Client$1 = Client> {
+interface CommandContext<TClient extends Client$1 = Client> {
     /** The client instance */
     client: TClient;
     /** The raw message content */
@@ -336,82 +285,71 @@ interface CommandContext<TOptions = Record<string, string | number | boolean>, T
     channelId: string;
     /** The server/guild ID (if applicable) */
     serverId?: string | undefined;
-    /** Parsed command arguments */
-    args: TArgs;
-    options?: TOptions;
     /** The prefix used */
     prefix: string;
     /** The command name used (could be an alias) */
     commandName: string;
     /** Reply to the message */
     reply: (content: string) => Promise<Message>;
-    /** The original message object (platform-specific) */
+    /** The original message object */
     message: Message;
 }
 /**
  * Optional lifecycle hooks for @Stoat() class instances
  */
 interface StoatLifecycle {
-    /** Optional: Called when an error occurs during command execution */
-    onError?(ctx: CommandContext<Client>, error: Error): Promise<void> | void;
-    /** Optional: Called when a cooldown is active */
-    onCooldown?(ctx: CommandContext<Client>, remaining: number): Promise<void> | void;
-    /** Optional: Called when user doesn't have the permissions needed */
-    onMissingPermissions?(ctx: CommandContext<Client>, missing: PermissionResolvable[]): Promise<void> | void;
-    /** Allows the class to contain other methods (such as your commands) */
+    onError?(ctx: CommandContext, error: Error): Promise<void> | void;
+    onValidationError?(ctx: CommandContext, error: CommandValidationError): Promise<void> | void;
+    onCooldown?(ctx: CommandContext, remaining: number): Promise<void> | void;
+    onMissingPermissions?(ctx: CommandContext, missing: PermissionResolvable[]): Promise<void> | void;
     [method: string]: any;
 }
+interface GuardInterface {
+    run(ctx: CommandContext): Promise<boolean> | boolean;
+    guardFail?(ctx: CommandContext): Promise<void> | void;
+}
 /**
- * Cooldown manager interface for custom cooldown storage (e.g., database)
+ * Cooldown manager interface for custom cooldown storage
  */
 interface CooldownManager {
-    check(ctx: CommandContext<any>, metadata: CommandMetadata): boolean | Promise<boolean>;
-    getRemaining(ctx: CommandContext<any>, metadata: CommandMetadata): number | Promise<number>;
-    set(ctx: CommandContext<any>, metadata: CommandMetadata): void | Promise<void>;
+    check(ctx: CommandContext, metadata: CommandMetadata): boolean | Promise<boolean>;
+    getRemaining(ctx: CommandContext, metadata: CommandMetadata): number | Promise<number>;
+    set(ctx: CommandContext, metadata: CommandMetadata): void | Promise<void>;
     clear?(): void | Promise<void>;
 }
 interface StoatxGuard {
-    run(ctx: CommandContext<Client>): Promise<boolean> | boolean;
-    guardFail?(ctx: CommandContext<Client>): Promise<void> | void;
+    run(ctx: CommandContext): Promise<boolean> | boolean;
+    guardFail?(ctx: CommandContext): Promise<void> | void;
 }
 /**
  * Discovery options for automatic command module loading
  */
 interface StoatxDiscoveryOptions {
-    /** Root directories to scan (default: [process.cwd()]) */
     roots?: string[];
-    /** Glob patterns relative to each root */
     include?: string[];
-    /** Additional ignore patterns */
     ignore?: string[];
 }
 /**
  * Handler options
  */
 interface StoatxHandlerOptions {
-    /** The client instance */
     client: Client;
-    /** Directory to scan for command modules (absolute path) */
     commandsDir?: string;
-    /** Auto-discovery options used when commandsDir is not provided */
     discovery?: StoatxDiscoveryOptions;
-    /** Command prefix or prefix resolver function */
-    prefix: string | ((ctx: {
+    prefix: string | string[] | ((ctx: {
         serverId?: string | undefined;
-    }) => string | Promise<string>);
-    /** Owner IDs for owner-only commands */
+    }) => string | string[] | Promise<string | string[]>);
     owners?: string[];
-    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
     extensions?: string[];
-    /** Disable mention prefix support (default: false) */
     disableMentionPrefix?: boolean;
-    /** Custom cooldown manager */
     cooldownManager?: CooldownManager;
-    /** * The prefix used to identify flags/options (defaults to "-")
-     * @example "+" for +force, "/" for /force
-     */
     flagPrefix?: string;
+    globalGuards?: Function[];
 }
+/**
+ * Map from reflect-metadata design:paramtypes constructor to resolved param type
+ */
+declare const PARAM_TYPE_MAP: Map<Function, ResolvedParamType>;
 
 /**
  * @Stoat
@@ -449,7 +387,7 @@ interface SimpleCommandDefinition {
     methodName: string;
     options: SimpleCommandOptions;
 }
-type CommandMethod = (ctx: CommandContext) => Promise<void>;
+type CommandMethod = (...args: any[]) => Promise<void>;
 /**
  * @SimpleCommand
  * Marks a method as a simple command within a @Stoat() decorated class.
@@ -507,11 +445,11 @@ declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
  * }
  * ```
  */
-declare function Guard(guardClass: Function): ClassDecorator;
+declare function Guard(guardClass: Function): (target: any, propertyKey?: string | symbol) => void;
 /**
  * Get all guards from a decorated class
  */
-declare function getGuards(target: Function): Function[];
+declare function getGuards(target: Function, propertyKey?: string | symbol): Function[];
 
 interface EventDefinition {
     methodName: string;
@@ -539,7 +477,7 @@ interface EventDefinition {
  *
  * @param event The name of the client event to listen to
  */
-declare function On(event: string): MethodDecorator;
+declare function On(event: keyof ClientEvents): MethodDecorator;
 /**
  * @Once
  * Triggered only fully once.
@@ -561,16 +499,66 @@ declare function On(event: string): MethodDecorator;
  *
  * @param event The name of the client event to listen to
  */
-declare function Once(event: string): MethodDecorator;
+declare function Once(event: keyof ClientEvents): MethodDecorator;
 /**
  * Get all event definitions from a @Stoat class
  */
 declare function getEventsMetadata(target: Function): EventDefinition[];
 
+interface ArgDefinition {
+    index: number;
+    name?: string;
+    required?: boolean;
+    fetch?: boolean;
+}
+/**
+ * Marks a method parameter as a positional command argument.
+ * Type is inferred from the TypeScript parameter type via reflect-metadata.
+ *
+ * @example
+ * ```ts
+ * @SimpleCommand({ name: "ban" })
+ * async ban(
+ *   @Arg({ required: true }) target: User,
+ *   @Arg() reason: string | undefined,
+ *   ctx: CommandContext
+ * ) {}
+ * ```
+ */
+declare function Arg(options?: Omit<ArgDefinition, "index">): (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+
+interface OptionDefinition {
+    index: number;
+    name: string;
+    required?: boolean;
+}
+/**
+ * @Option
+ * Marks a method parameter as a named flag option (e.g. --reason value).
+ * Type is inferred from the TypeScript parameter type via reflect-metadata.
+ *
+ * @example
+ * ```ts
+ * @SimpleCommand({ name: "ban" })
+ * async ban(
+ *   @Option({ name: "reason" }) reason: string | undefined,
+ *   @Option({ name: "days" }) days: number | undefined,
+ *   ctx: CommandContext
+ * ) {}
+ * ```
+ */
+declare function Option(options: Omit<OptionDefinition, "index">): (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+
+declare function Injectable(): ClassDecorator;
+
+declare function CommandGroup(name: GroupOptions): ClassDecorator;
+
+declare function SubCommand(options: SimpleCommandOptions | string): MethodDecorator;
+
 /**
  * Build CommandMetadata from SimpleCommandOptions
  */
-declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category?: string): CommandMetadata;
+declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, methodName: string, category: string | undefined, params: ParamSchema[]): CommandMetadata;
 
 /**
  * Metadata keys used by decorators
@@ -580,11 +568,11 @@ declare const METADATA_KEYS: {
     readonly SIMPLE_COMMANDS: symbol;
     readonly GUARDS: "stoatx:command:guards";
     readonly EVENTS: symbol;
+    readonly ARGS: symbol;
+    readonly OPTIONS: symbol;
+    readonly INJECTABLE: symbol;
+    readonly SUBCOMMAND: symbol;
+    readonly COMMAND_GROUP: symbol;
 };
 
-declare class CommandValidationError extends Error {
-    readonly optionName: string;
-    constructor(optionName: string, message: string);
-}
-
-export { Client, type CommandContext, type CommandMetadata, type CommandOptionDefinition, CommandRegistry, CommandValidationError, type CooldownManager, DefaultCooldownManager, type EventDefinition, Guard, METADATA_KEYS, On, Once, type OptionType, type RegisteredCommand, type RegisteredEvent, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, type StoatxDiscoveryOptions, type StoatxGuard, StoatxHandler, type StoatxHandlerOptions, buildSimpleCommandMetadata, getEventsMetadata, getGuards, getSimpleCommands, isStoatClass };
+export { Arg, Client, type CommandContext, CommandGroup, type CommandMetadata, CommandRegistry, CommandValidationError, type CooldownManager, DefaultCooldownManager, type EventDefinition, FetchFailedError, type GroupOptions, Guard, type GuardInterface, Injectable, InvalidMentionError, InvalidTypeError, METADATA_KEYS, MissingArgumentError, MissingOptionError, NoServerContextError, On, Once, Option, PARAM_TYPE_MAP, type ParamSchema, type RegisteredCommand, type RegisteredEvent, type ResolvedParamType, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, type StoatxDiscoveryOptions, StoatxError, type StoatxGuard, StoatxHandler, type StoatxHandlerOptions, SubCommand, buildSimpleCommandMetadata, getEventsMetadata, getGuards, getSimpleCommands, isStoatClass };