stoatx 0.4.0 → 0.5.0

package/dist/registry.d.ts

@@ -0,0 +1,125 @@
+import type { CommandMetadata } from "./types";
+interface AutoDiscoveryOptions {
+    roots?: string[];
+    include?: string[];
+    ignore?: string[];
+}
+/**
+ * Stored command entry from @Stoat/@SimpleCommand registration.
+ */
+export 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.
+ */
+export 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();
+ * ```
+ */
+export declare class CommandRegistry {
+    private static readonly DEFAULT_AUTO_DISCOVERY_IGNORES;
+    private readonly commands;
+    private readonly aliases;
+    private readonly registeredEvents;
+    private readonly extensions;
+    private readonly processedStoatClasses;
+    constructor(extensions?: string[]);
+    /**
+     * Get the number of registered commands
+     */
+    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
+     */
+    private getCategoryFromPath;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,UAAU,oBAAoB;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,QAAQ,EAAE,eAAe,CAAC;IAC1B,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,gBAAgB,EAAE,QAAQ,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,8BAA8B,CAMpD;IAEF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA4B;gBAEtD,UAAU,GAAE,MAAM,EAA4B;IAI1D;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBzD;;OAEG;IACG,YAAY,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCrE,OAAO,CAAC,+BAA+B;YAKzB,qBAAqB;IAenC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAsB3G;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAMhD;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK1B;;OAEG;IACH,MAAM,IAAI,iBAAiB,EAAE;IAI7B;;OAEG;IACH,cAAc,IAAI,eAAe,EAAE;IAInC;;OAEG;IACH,SAAS,IAAI,eAAe,EAAE;IAI9B;;OAEG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAajD;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAIlE;;OAEG;IACH,MAAM,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;IAI7C;;OAEG;IACH,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIhC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAuBtB;;OAEG;YACW,QAAQ;IAkBtB,OAAO,CAAC,0BAA0B;IA0ClC;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAU5B"}

package/dist/registry.js

@@ -0,0 +1,279 @@
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { glob } from "tinyglobby";
+import { buildSimpleCommandMetadata, getSimpleCommands, getEventsMetadata } from "./decorators";
+import { decoratorStore } from "./decorators/store";
+/**
+ * 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();
+ * ```
+ */
+export class CommandRegistry {
+    static DEFAULT_AUTO_DISCOVERY_IGNORES = [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/*.d.ts",
+        "**/*.test.*",
+        "**/*.spec.*",
+    ];
+    commands = new Map();
+    aliases = new Map();
+    registeredEvents = [];
+    extensions;
+    processedStoatClasses = new Set();
+    constructor(extensions = [".js", ".mjs", ".cjs"]) {
+        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 glob(pattern, {
+                ignore: ["**/*.d.ts", "**/*.test.ts", "**/*.spec.ts"],
+                absolute: true,
+            });
+            for (const file of files) {
+                await this.loadFile(file, directory);
+            }
+        }
+        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 includePatterns = options.include?.length ? options.include : this.getDefaultAutoDiscoveryPatterns();
+        const patterns = roots.flatMap((root) => includePatterns.map((pattern) => path.join(root, pattern).replace(/\\/g, "/")));
+        const files = await glob(patterns, {
+            ignore: [...CommandRegistry.DEFAULT_AUTO_DISCOVERY_IGNORES, ...(options.ignore ?? [])],
+            absolute: true,
+        });
+        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 relative = path.relative(root, file);
+                return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+            }) ?? roots[0];
+            await this.loadFile(file, baseDir);
+        }
+        console.log(`[Stoatx] Loaded ${this.commands.size} command(s) and ${this.registeredEvents.length} event(s)`);
+    }
+    getDefaultAutoDiscoveryPatterns() {
+        // discordx-like default: scan broadly, then register only decorated classes
+        return this.extensions.map((ext) => `**/*${ext}`);
+    }
+    async isLikelyCommandModule(filePath) {
+        try {
+            const source = await fs.readFile(filePath, "utf8");
+            return (source.includes("Stoat") ||
+                source.includes("SimpleCommand") ||
+                source.includes("Command") ||
+                source.includes("stoatx:command"));
+        }
+        catch {
+            // If the file can't be pre-read, fall back to attempting import.
+            return true;
+        }
+    }
+    /**
+     * Register a command instance
+     */
+    register(instance, metadata, classConstructor, methodName) {
+        const name = 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 });
+        for (const alias of metadata.aliases) {
+            const aliasLower = alias.toLowerCase();
+            if (this.aliases.has(aliasLower) || this.commands.has(aliasLower)) {
+                console.warn(`[Stoatx] Duplicate alias: ${aliasLower}. Skipping...`);
+                continue;
+            }
+            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 = new Map();
+        for (const cmd of this.commands.values()) {
+            const category = cmd.metadata.category;
+            const existing = categories.get(category) ?? [];
+            existing.push(cmd);
+            categories.set(category, existing);
+        }
+        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) || [];
+        for (const GuardClass of guards) {
+            const guardInstance = new GuardClass();
+            if (typeof guardInstance.run !== "function") {
+                console.error(`[Stoatx] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`);
+                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()) {
+                if (knownStoatClasses.has(stoatClass) || this.processedStoatClasses.has(stoatClass)) {
+                    continue;
+                }
+                this.registerStoatClassCommands(stoatClass, stoatInstance, filePath, baseDir);
+            }
+        }
+        catch (error) {
+            console.error(`[Stoatx] Failed to load command file: ${filePath}`, error);
+        }
+    }
+    registerStoatClassCommands(stoatClass, instance, filePath, baseDir) {
+        const simpleCommands = getSimpleCommands(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...`);
+            this.processedStoatClasses.add(stoatClass);
+            return;
+        }
+        for (const cmdDef of simpleCommands) {
+            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);
+            this.register(instance, metadata, stoatClass, cmdDef.methodName);
+        }
+        for (const eventDef of events) {
+            const method = instance[eventDef.methodName];
+            if (typeof method !== "function") {
+                console.warn(`[Stoatx] Method ${eventDef.methodName} not found on ${stoatClass.name}. Skipping...`);
+                continue;
+            }
+            this.registeredEvents.push({
+                instance,
+                methodName: eventDef.methodName,
+                event: eventDef.event,
+                type: eventDef.type,
+            });
+        }
+        this.processedStoatClasses.add(stoatClass);
+    }
+    /**
+     * Derive category from file path relative to base directory
+     */
+    getCategoryFromPath(filePath, baseDir) {
+        const relative = path.relative(baseDir, filePath);
+        const parts = relative.split(path.sep);
+        if (parts.length > 1) {
+            return parts[0];
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+import { Client as StoatClient, Message } from "stoat.js";
+/**
+ * Permission types for commands
+ */
+export type Permission = "SendMessages" | "ManageMessages" | "ManageChannels" | "ManageServer" | "KickMembers" | "BanMembers" | "Administrator" | (string & {});
+/**
+ * Simple command options passed to @SimpleCommand decorator
+ * Used with @Stoat() decorated classes for method-based commands
+ */
+export interface SimpleCommandOptions {
+    /** Command name (defaults to method name) */
+    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;
+}
+/**
+ * Resolved command metadata with required fields
+ */
+export interface CommandMetadata {
+    name: string;
+    description: string;
+    aliases: string[];
+    permissions: Permission[];
+    category: string;
+    cooldown: number;
+    nsfw: boolean;
+    ownerOnly: boolean;
+}
+/**
+ * Command execution context
+ */
+export interface CommandContext {
+    /** The client instance */
+    client: StoatClient;
+    /** The raw message content */
+    content: string;
+    /** The author ID */
+    authorId: string;
+    /** The channel ID */
+    channelId: string;
+    /** The server/guild ID (if applicable) */
+    serverId?: string;
+    /** Parsed command arguments */
+    args: string[];
+    /** 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) */
+    message: Message;
+}
+/**
+ * Optional lifecycle hooks for @Stoat() class instances
+ */
+export interface StoatLifecycle {
+    /** Optional: Called when an error occurs during command execution */
+    onError?(ctx: CommandContext, error: Error): Promise<void>;
+    /** Optional: Called when a cooldown is active */
+    onCooldown?(ctx: CommandContext, remaining: number): Promise<void>;
+}
+export interface StoatxGuard {
+    run(ctx: CommandContext): Promise<boolean> | boolean;
+    guardFail?(ctx: CommandContext): Promise<void> | void;
+}
+/**
+ * Discovery options for automatic command module loading
+ */
+export 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
+ */
+export interface StoatxHandlerOptions {
+    /** The client instance */
+    client: StoatClient;
+    /** 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: {
+        serverId?: string;
+    }) => string | Promise<string>);
+    /** Owner IDs for owner-only commands */
+    owners?: string[];
+    /** File extensions to load (default: ['.js', '.mjs', '.cjs']) */
+    extensions?: string[];
+    /** Disable mention prefix support (default: false) */
+    disableMentionPrefix?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stoatx",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A high-performance, decorator-based command handler for the Stoat ecosystem.",
   "repository": {
     "type": "git",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "stoat.js": "^7.3.6",
-    "tinyglobby": "^0.2.10"
+    "tinyglobby": "^0.2.10",
+    "@stoatx/client": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",