@marshmallow-stoat/mally 0.1.2 → 0.2.0

package/README.md

@@ -38,15 +38,13 @@ Make sure to enable decorators in your `tsconfig.json`:
 import 'reflect-metadata';
 import { Client } from 'stoat.js';
 import { MallyHandler } from '@marshmallow-stoat/mally';
-import { join } from 'path';
 
 const client = new Client();
 
 const handler = new MallyHandler({
     client, 
     prefix: '!', 
-    owners: ['your-user-id'], 
-    commandsDir: join(__dirname, "commands")
+    owners: ['your-user-id']
 });
 
 await handler.init();
@@ -78,7 +76,7 @@ export class GeneralCommands {
 }
 ```
 
-That's it! No manual imports needed - commands are auto-discovered.
+That's it! No manual imports needed - decorated command classes are auto-discovered.
 
 ## Decorators
 
@@ -165,12 +163,20 @@ interface Context {
 ```typescript
 interface MallyHandlerOptions {
   client: Client;
-  commandsDir: string;           // Directory to scan for commands
+  commandsDir?: string;          // Legacy mode: explicitly scan this directory
+  discovery?: {
+    roots?: string[];            // Default: [process.cwd()]
+    include?: string[];          // Glob patterns per root
+    ignore?: string[];           // Additional ignore globs
+  };
   prefix: string | ((ctx: { serverId?: string }) => string | Promise<string>);
   owners?: string[];             // Owner user IDs
-  extensions?: string[];         // File extensions (default: ['.js', '.ts'])
+  extensions?: string[];         // File extensions (default: ['.js', '.mjs', '.cjs'])
   disableMentionPrefix?: boolean; // Disable @bot prefix
 }
+
+// Default auto-discovery is discordx-like: scans broadly under process.cwd(),
+// then registers only files that look like decorated command modules.
 ```
 
 ## Dynamic Prefix
@@ -178,32 +184,35 @@ interface MallyHandlerOptions {
 ```typescript
 const handler = new MallyHandler({
   client,
-  commandsDir: join(__dirname, 'commands'),
   prefix: async ({ serverId }) => {
     // Fetch from database, etc.
     return serverId ? await getServerPrefix(serverId) : '!';
   },
 });
-```
-
-## Legacy Class-Based Commands
-
-You can also use the class-based approach:
 
-```typescript
-import { Command, BaseCommand, Context } from '@marshmallow-stoat/mally';
+// Optional: constrain auto-discovery to specific roots/patterns
+const scopedHandler = new MallyHandler({
+  client,
+  prefix: '!',
+  discovery: {
+    roots: [process.cwd()],
+    include: ['apps/bot/dist/commands/**/*.js'],
+  },
+});
 
-@Command({
-  name: 'ping',
-  description: 'Ping command',
-})
-export class PingCommand extends BaseCommand {
-  async run(ctx: Context) {
-    await ctx.reply('Pong!');
-  }
-}
+// TypeScript source discovery is opt-in and requires a TS runtime loader (tsx/ts-node)
+const tsRuntimeHandler = new MallyHandler({
+  client,
+  prefix: '!',
+  extensions: ['.ts'],
+  discovery: {
+    include: ['apps/bot/src/commands/**/*.ts'],
+  },
+});
 ```
 
+All commands are defined through `@Stoat()` classes and `@SimpleCommand()` methods.
+
 ## License
 
 AGPL-3.0-or-later

package/dist/index.d.mts

@@ -4,27 +4,6 @@ import { Client, Message } from 'stoat.js';
  * Permission types for commands
  */
 type Permission = "SendMessages" | "ManageMessages" | "ManageChannels" | "ManageServer" | "KickMembers" | "BanMembers" | "Administrator" | (string & {});
-/**
- * Command metadata options passed to @Command decorator
- */
-interface CommandOptions {
-    /** Command name (defaults to class name without 'Command' suffix) */
-    name?: string;
-    /** Command description */
-    description?: string;
-    /** Command aliases */
-    aliases?: string[];
-    /** Required permissions to run the command */
-    permissions?: Permission[];
-    /** Command category (auto-detected from directory if not provided) */
-    category?: string;
-    /** Cooldown in milliseconds */
-    cooldown?: number;
-    /** Whether the command is NSFW only */
-    nsfw?: boolean;
-    /** Whether the command is owner only */
-    ownerOnly?: boolean;
-}
 /**
  * Simple command options passed to @SimpleCommand decorator
  * Used with @Stoat() decorated classes for method-based commands
@@ -86,20 +65,12 @@ interface CommandContext {
     message: Message;
 }
 /**
- * Interface that all command classes must implement
+ * Optional lifecycle hooks for @Stoat() class instances
  */
-interface MallyCommand {
-    /** Command metadata (injected by registry) */
-    metadata: CommandMetadata;
-    /**
-     * Execute the command
-     */
-    run(ctx: CommandContext): Promise<void>;
-    /**
-     * Optional: Called when an error occurs during command execution
-     */
+interface StoatLifecycle {
+    /** Optional: Called when an error occurs during command execution */
     onError?(ctx: CommandContext, error: Error): Promise<void>;
-    guardFail?(ctx: CommandContext): Promise<void>;
+    /** Optional: Called when a cooldown is active */
     onCooldown?(ctx: CommandContext, remaining: number): Promise<void>;
 }
 interface MallyGuard {
@@ -107,53 +78,33 @@ interface MallyGuard {
     guardFail?(ctx: CommandContext): Promise<void> | void;
 }
 /**
- * Abstract base class for commands.
- * Extend this class to create commands without boilerplate.
- *
- * @example
- * ```ts
- * @Command({ name: 'ping', description: 'Replies with Pong!' })
- * export class PingCommand extends BaseCommand {
- *   async run(ctx) {
- *     await ctx.reply('Pong!');
- *   }
- * }
- * ```
+ * Discovery options for automatic command module loading
  */
-declare abstract class BaseCommand implements MallyCommand {
-    /** Command metadata (injected by registry) */
-    metadata: CommandMetadata;
-    /** Typed context for use in subclasses */
-    protected ctx: CommandContext;
-    /**
-     * Execute the command - must be implemented by subclasses
-     */
-    abstract run(ctx: CommandContext): Promise<void>;
-    /**
-     * Optional: Called when an error occurs during command execution.
-     * Override this method to provide custom error handling.
-     */
-    onError(ctx: CommandContext, error: Error): Promise<void>;
+interface MallyDiscoveryOptions {
+    /** Root directories to scan (default: [process.cwd()]) */
+    roots?: string[];
+    /** Glob patterns relative to each root */
+    include?: string[];
+    /** Additional ignore patterns */
+    ignore?: string[];
 }
-/**
- * Constructor type for command classes
- */
-type CommandConstructor = new () => MallyCommand;
 /**
  * Handler options
  */
 interface MallyHandlerOptions {
     /** The client instance */
     client: Client;
-    /** Directory to scan for commands (absolute path) */
-    commandsDir: string;
+    /** Directory to scan for command modules (absolute path) */
+    commandsDir?: string;
+    /** Auto-discovery options used when commandsDir is not provided */
+    discovery?: MallyDiscoveryOptions;
     /** Command prefix or prefix resolver function */
     prefix: string | ((ctx: {
         serverId?: string;
     }) => string | Promise<string>);
     /** Owner IDs for owner-only commands */
     owners?: string[];
-    /** File extensions to load (default: ['.js', '.ts']) */
+    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
     extensions?: string[];
     /** Disable mention prefix support (default: false) */
     disableMentionPrefix?: boolean;
@@ -221,49 +172,11 @@ declare function SimpleCommand(options?: SimpleCommandOptions): MethodDecorator;
  */
 declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
 
-/**
- * @Command
- * Marks a class as a command and attaches metadata.
- * This is the legacy/class-based approach where each command is a separate class.
- *
- * @example
- * ```ts
- * import { Command, MallyCommand, CommandContext } from '@marshmallow/mally';
- *
- * @Command({
- *   description: 'Ban a user from the server',
- *   aliases: ['b'],
- *   permissions: ['BanMembers']
- * })
- * export class BanCommand implements MallyCommand {
- *   metadata!: CommandMetadata;
- *
- *   async run(ctx: CommandContext) {
- *     const userId = ctx.args[0];
- *     await ctx.reply(`Banned user ${userId}`);
- *   }
- * }
- * ```
- */
-declare function Command(options?: CommandOptions): ClassDecorator;
-/**
- * Check if a class is decorated with @Command
- */
-declare function isCommand(target: Function): boolean;
-/**
- * Get command options from a decorated class
- */
-declare function getCommandOptions(target: Function): CommandOptions | undefined;
-/**
- * Build complete CommandMetadata from options and class name
- */
-declare function buildCommandMetadata(target: Function, options: CommandOptions, category?: string): CommandMetadata;
-
 /**
  * @Guard
  * Runs before a command to check if it should execute.
  * Should return true to allow execution, false to block.
- * Can be applied to both @Command classes and @Stoat classes.
+ * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
  *
  * @example
  * ```ts
@@ -305,23 +218,26 @@ declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, metho
  * Metadata keys used by decorators
  */
 declare const METADATA_KEYS: {
-    readonly COMMAND_OPTIONS: symbol;
-    readonly IS_COMMAND: symbol;
     readonly IS_STOAT_CLASS: symbol;
     readonly SIMPLE_COMMANDS: symbol;
     readonly GUARDS: "mally:command:guards";
 };
 
+interface AutoDiscoveryOptions {
+    roots?: string[];
+    include?: string[];
+    ignore?: string[];
+}
 /**
- * Stored command entry (supports both class-based and method-based commands)
+ * Stored command entry from @Stoat/@SimpleCommand registration.
  */
 interface RegisteredCommand {
-    /** Instance of the command class */
-    instance: MallyCommand | object;
+    /** Instance of the @Stoat class */
+    instance: object;
     /** Command metadata */
     metadata: CommandMetadata;
-    /** Method name to call (for @SimpleCommand methods) */
-    methodName?: string;
+    /** Method name to call */
+    methodName: string;
     /** The original class constructor (for guard validation) */
     classConstructor: Function;
 }
@@ -338,9 +254,11 @@ interface RegisteredCommand {
  * ```
  */
 declare class CommandRegistry {
+    private static readonly DEFAULT_AUTO_DISCOVERY_IGNORES;
     private readonly commands;
     private readonly aliases;
     private readonly extensions;
+    private readonly processedStoatClasses;
     constructor(extensions?: string[]);
     /**
      * Get the number of registered commands
@@ -350,10 +268,16 @@ declare class CommandRegistry {
      * 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: MallyCommand | object, metadata: CommandMetadata, classConstructor: Function, methodName?: string): void;
+    register(instance: object, metadata: CommandMetadata, classConstructor: Function, methodName: string): void;
     /**
      * Get a command by name or alias
      */
@@ -397,17 +321,11 @@ declare class CommandRegistry {
      * @private
      */
     private validateGuards;
-    /**
-     * Validate that commands with cooldowns implement the onCooldown method
-     * @param instance
-     * @param metadata
-     * @private
-     */
-    private validateCooldown;
     /**
      * Load commands from a single file
      */
     private loadFile;
+    private registerStoatClassCommands;
     /**
      * Derive category from file path relative to base directory
      */
@@ -428,7 +346,6 @@ declare class CommandRegistry {
  *
  * const handler = new MallyHandler({
  *   client,
- *   commandsDir: path.join(__dirname, 'commands'),
  *   prefix: '!',
  *   owners: ['owner-user-id'],
  * });
@@ -441,7 +358,8 @@ declare class CommandRegistry {
  * ```
  */
 declare class MallyHandler {
-    private readonly commandsDir;
+    private readonly commandsDir?;
+    private readonly discoveryOptions?;
     private readonly prefixResolver;
     private readonly owners;
     private readonly registry;
@@ -546,4 +464,4 @@ declare class MallyHandler {
     private setCooldown;
 }
 
-export { BaseCommand, Command, type CommandConstructor, type CommandContext, type CommandMetadata, type CommandOptions, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyCommand, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, buildCommandMetadata, buildSimpleCommandMetadata, getCommandOptions, getGuards, getSimpleCommands, isCommand, isStoatClass };
+export { type CommandContext, type CommandMetadata, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyDiscoveryOptions, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, buildSimpleCommandMetadata, getGuards, getSimpleCommands, isStoatClass };

package/dist/index.d.ts

@@ -4,27 +4,6 @@ import { Client, Message } from 'stoat.js';
  * Permission types for commands
  */
 type Permission = "SendMessages" | "ManageMessages" | "ManageChannels" | "ManageServer" | "KickMembers" | "BanMembers" | "Administrator" | (string & {});
-/**
- * Command metadata options passed to @Command decorator
- */
-interface CommandOptions {
-    /** Command name (defaults to class name without 'Command' suffix) */
-    name?: string;
-    /** Command description */
-    description?: string;
-    /** Command aliases */
-    aliases?: string[];
-    /** Required permissions to run the command */
-    permissions?: Permission[];
-    /** Command category (auto-detected from directory if not provided) */
-    category?: string;
-    /** Cooldown in milliseconds */
-    cooldown?: number;
-    /** Whether the command is NSFW only */
-    nsfw?: boolean;
-    /** Whether the command is owner only */
-    ownerOnly?: boolean;
-}
 /**
  * Simple command options passed to @SimpleCommand decorator
  * Used with @Stoat() decorated classes for method-based commands
@@ -86,20 +65,12 @@ interface CommandContext {
     message: Message;
 }
 /**
- * Interface that all command classes must implement
+ * Optional lifecycle hooks for @Stoat() class instances
  */
-interface MallyCommand {
-    /** Command metadata (injected by registry) */
-    metadata: CommandMetadata;
-    /**
-     * Execute the command
-     */
-    run(ctx: CommandContext): Promise<void>;
-    /**
-     * Optional: Called when an error occurs during command execution
-     */
+interface StoatLifecycle {
+    /** Optional: Called when an error occurs during command execution */
     onError?(ctx: CommandContext, error: Error): Promise<void>;
-    guardFail?(ctx: CommandContext): Promise<void>;
+    /** Optional: Called when a cooldown is active */
     onCooldown?(ctx: CommandContext, remaining: number): Promise<void>;
 }
 interface MallyGuard {
@@ -107,53 +78,33 @@ interface MallyGuard {
     guardFail?(ctx: CommandContext): Promise<void> | void;
 }
 /**
- * Abstract base class for commands.
- * Extend this class to create commands without boilerplate.
- *
- * @example
- * ```ts
- * @Command({ name: 'ping', description: 'Replies with Pong!' })
- * export class PingCommand extends BaseCommand {
- *   async run(ctx) {
- *     await ctx.reply('Pong!');
- *   }
- * }
- * ```
+ * Discovery options for automatic command module loading
  */
-declare abstract class BaseCommand implements MallyCommand {
-    /** Command metadata (injected by registry) */
-    metadata: CommandMetadata;
-    /** Typed context for use in subclasses */
-    protected ctx: CommandContext;
-    /**
-     * Execute the command - must be implemented by subclasses
-     */
-    abstract run(ctx: CommandContext): Promise<void>;
-    /**
-     * Optional: Called when an error occurs during command execution.
-     * Override this method to provide custom error handling.
-     */
-    onError(ctx: CommandContext, error: Error): Promise<void>;
+interface MallyDiscoveryOptions {
+    /** Root directories to scan (default: [process.cwd()]) */
+    roots?: string[];
+    /** Glob patterns relative to each root */
+    include?: string[];
+    /** Additional ignore patterns */
+    ignore?: string[];
 }
-/**
- * Constructor type for command classes
- */
-type CommandConstructor = new () => MallyCommand;
 /**
  * Handler options
  */
 interface MallyHandlerOptions {
     /** The client instance */
     client: Client;
-    /** Directory to scan for commands (absolute path) */
-    commandsDir: string;
+    /** Directory to scan for command modules (absolute path) */
+    commandsDir?: string;
+    /** Auto-discovery options used when commandsDir is not provided */
+    discovery?: MallyDiscoveryOptions;
     /** Command prefix or prefix resolver function */
     prefix: string | ((ctx: {
         serverId?: string;
     }) => string | Promise<string>);
     /** Owner IDs for owner-only commands */
     owners?: string[];
-    /** File extensions to load (default: ['.js', '.ts']) */
+    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
     extensions?: string[];
     /** Disable mention prefix support (default: false) */
     disableMentionPrefix?: boolean;
@@ -221,49 +172,11 @@ declare function SimpleCommand(options?: SimpleCommandOptions): MethodDecorator;
  */
 declare function getSimpleCommands(target: Function): SimpleCommandDefinition[];
 
-/**
- * @Command
- * Marks a class as a command and attaches metadata.
- * This is the legacy/class-based approach where each command is a separate class.
- *
- * @example
- * ```ts
- * import { Command, MallyCommand, CommandContext } from '@marshmallow/mally';
- *
- * @Command({
- *   description: 'Ban a user from the server',
- *   aliases: ['b'],
- *   permissions: ['BanMembers']
- * })
- * export class BanCommand implements MallyCommand {
- *   metadata!: CommandMetadata;
- *
- *   async run(ctx: CommandContext) {
- *     const userId = ctx.args[0];
- *     await ctx.reply(`Banned user ${userId}`);
- *   }
- * }
- * ```
- */
-declare function Command(options?: CommandOptions): ClassDecorator;
-/**
- * Check if a class is decorated with @Command
- */
-declare function isCommand(target: Function): boolean;
-/**
- * Get command options from a decorated class
- */
-declare function getCommandOptions(target: Function): CommandOptions | undefined;
-/**
- * Build complete CommandMetadata from options and class name
- */
-declare function buildCommandMetadata(target: Function, options: CommandOptions, category?: string): CommandMetadata;
-
 /**
  * @Guard
  * Runs before a command to check if it should execute.
  * Should return true to allow execution, false to block.
- * Can be applied to both @Command classes and @Stoat classes.
+ * Applied on @Stoat classes to guard all contained @SimpleCommand methods.
  *
  * @example
  * ```ts
@@ -305,23 +218,26 @@ declare function buildSimpleCommandMetadata(options: SimpleCommandOptions, metho
  * Metadata keys used by decorators
  */
 declare const METADATA_KEYS: {
-    readonly COMMAND_OPTIONS: symbol;
-    readonly IS_COMMAND: symbol;
     readonly IS_STOAT_CLASS: symbol;
     readonly SIMPLE_COMMANDS: symbol;
     readonly GUARDS: "mally:command:guards";
 };
 
+interface AutoDiscoveryOptions {
+    roots?: string[];
+    include?: string[];
+    ignore?: string[];
+}
 /**
- * Stored command entry (supports both class-based and method-based commands)
+ * Stored command entry from @Stoat/@SimpleCommand registration.
  */
 interface RegisteredCommand {
-    /** Instance of the command class */
-    instance: MallyCommand | object;
+    /** Instance of the @Stoat class */
+    instance: object;
     /** Command metadata */
     metadata: CommandMetadata;
-    /** Method name to call (for @SimpleCommand methods) */
-    methodName?: string;
+    /** Method name to call */
+    methodName: string;
     /** The original class constructor (for guard validation) */
     classConstructor: Function;
 }
@@ -338,9 +254,11 @@ interface RegisteredCommand {
  * ```
  */
 declare class CommandRegistry {
+    private static readonly DEFAULT_AUTO_DISCOVERY_IGNORES;
     private readonly commands;
     private readonly aliases;
     private readonly extensions;
+    private readonly processedStoatClasses;
     constructor(extensions?: string[]);
     /**
      * Get the number of registered commands
@@ -350,10 +268,16 @@ declare class CommandRegistry {
      * 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: MallyCommand | object, metadata: CommandMetadata, classConstructor: Function, methodName?: string): void;
+    register(instance: object, metadata: CommandMetadata, classConstructor: Function, methodName: string): void;
     /**
      * Get a command by name or alias
      */
@@ -397,17 +321,11 @@ declare class CommandRegistry {
      * @private
      */
     private validateGuards;
-    /**
-     * Validate that commands with cooldowns implement the onCooldown method
-     * @param instance
-     * @param metadata
-     * @private
-     */
-    private validateCooldown;
     /**
      * Load commands from a single file
      */
     private loadFile;
+    private registerStoatClassCommands;
     /**
      * Derive category from file path relative to base directory
      */
@@ -428,7 +346,6 @@ declare class CommandRegistry {
  *
  * const handler = new MallyHandler({
  *   client,
- *   commandsDir: path.join(__dirname, 'commands'),
  *   prefix: '!',
  *   owners: ['owner-user-id'],
  * });
@@ -441,7 +358,8 @@ declare class CommandRegistry {
  * ```
  */
 declare class MallyHandler {
-    private readonly commandsDir;
+    private readonly commandsDir?;
+    private readonly discoveryOptions?;
     private readonly prefixResolver;
     private readonly owners;
     private readonly registry;
@@ -546,4 +464,4 @@ declare class MallyHandler {
     private setCooldown;
 }
 
-export { BaseCommand, Command, type CommandConstructor, type CommandContext, type CommandMetadata, type CommandOptions, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyCommand, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, buildCommandMetadata, buildSimpleCommandMetadata, getCommandOptions, getGuards, getSimpleCommands, isCommand, isStoatClass };
+export { type CommandContext, type CommandMetadata, CommandRegistry, type CommandContext as Context, Guard, METADATA_KEYS, type MallyDiscoveryOptions, type MallyGuard, MallyHandler, type MallyHandlerOptions, type Permission, type RegisteredCommand, SimpleCommand, type SimpleCommandDefinition, type SimpleCommandOptions, Stoat, type StoatLifecycle, buildSimpleCommandMetadata, getGuards, getSimpleCommands, isStoatClass };