stoatx 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -0,0 +1,651 @@
+// src/decorators/Stoat.ts
+import "reflect-metadata";
+
+// src/decorators/keys.ts
+var METADATA_KEYS = {
+  IS_STOAT_CLASS: /* @__PURE__ */ Symbol("mally:stoat:isClass"),
+  SIMPLE_COMMANDS: /* @__PURE__ */ Symbol("mally:stoat:simpleCommands"),
+  GUARDS: "mally:command:guards"
+};
+
+// src/decorators/store.ts
+var DecoratorStore = class _DecoratorStore {
+  constructor() {
+    /** Stoat classes with their SimpleCommand methods */
+    this.stoatClasses = /* @__PURE__ */ new Map();
+    /** Registered commands from @Stoat/@SimpleCommand decorators */
+    this.commands = [];
+    /** Whether the store has been initialized */
+    this.initialized = false;
+  }
+  static getInstance() {
+    if (!_DecoratorStore.instance) {
+      _DecoratorStore.instance = new _DecoratorStore();
+    }
+    return _DecoratorStore.instance;
+  }
+  /**
+   * Register a @Stoat decorated class
+   */
+  registerStoatClass(classConstructor) {
+    if (!this.stoatClasses.has(classConstructor)) {
+      const instance = new classConstructor();
+      this.stoatClasses.set(classConstructor, instance);
+    }
+  }
+  /**
+   * Get all registered Stoat classes with their instances
+   */
+  getStoatClasses() {
+    return this.stoatClasses;
+  }
+  /**
+   * Add a registered command
+   */
+  addCommand(command) {
+    this.commands.push(command);
+  }
+  /**
+   * Get all registered commands
+   */
+  getCommands() {
+    return this.commands;
+  }
+  /**
+   * Clear all registered classes (useful for testing)
+   */
+  clear() {
+    this.stoatClasses.clear();
+    this.commands = [];
+    this.initialized = false;
+  }
+  /**
+   * Mark as initialized
+   */
+  markInitialized() {
+    this.initialized = true;
+  }
+  /**
+   * Check if initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+};
+var decoratorStore = DecoratorStore.getInstance();
+
+// src/decorators/Stoat.ts
+function Stoat() {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.IS_STOAT_CLASS, true, target);
+    decoratorStore.registerStoatClass(target);
+  };
+}
+function isStoatClass(target) {
+  return Reflect.getMetadata(METADATA_KEYS.IS_STOAT_CLASS, target) === true;
+}
+
+// src/decorators/SimpleCommand.ts
+import "reflect-metadata";
+function SimpleCommand(options = {}) {
+  return (target, propertyKey, descriptor) => {
+    const constructor = target.constructor;
+    const existingCommands = Reflect.getMetadata(METADATA_KEYS.SIMPLE_COMMANDS, constructor) || [];
+    existingCommands.push({
+      methodName: String(propertyKey),
+      options
+    });
+    Reflect.defineMetadata(METADATA_KEYS.SIMPLE_COMMANDS, existingCommands, constructor);
+    return descriptor;
+  };
+}
+function getSimpleCommands(target) {
+  return Reflect.getMetadata(METADATA_KEYS.SIMPLE_COMMANDS, target) || [];
+}
+
+// src/decorators/Guard.ts
+import "reflect-metadata";
+function Guard(guardClass) {
+  return (target) => {
+    const existingGuards = Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
+    existingGuards.push(guardClass);
+    Reflect.defineMetadata(METADATA_KEYS.GUARDS, existingGuards, target);
+  };
+}
+function getGuards(target) {
+  return Reflect.getMetadata(METADATA_KEYS.GUARDS, target) || [];
+}
+
+// src/decorators/utils.ts
+function buildSimpleCommandMetadata(options, methodName, category) {
+  return {
+    name: options.name ?? methodName.toLowerCase(),
+    description: options.description ?? "No description provided",
+    aliases: options.aliases ?? [],
+    permissions: options.permissions ?? [],
+    category: options.category ?? category ?? "uncategorized",
+    cooldown: options.cooldown ?? 0,
+    nsfw: options.nsfw ?? false,
+    ownerOnly: options.ownerOnly ?? false
+  };
+}
+
+// src/registry.ts
+import * as path from "path";
+import * as fs from "fs/promises";
+import { pathToFileURL } from "url";
+import { glob } from "tinyglobby";
+var _CommandRegistry = class _CommandRegistry {
+  constructor(extensions = [".js", ".mjs", ".cjs"]) {
+    this.commands = /* @__PURE__ */ new Map();
+    this.aliases = /* @__PURE__ */ new Map();
+    this.processedStoatClasses = /* @__PURE__ */ new Set();
+    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(`[Mally] Loaded ${this.commands.size} command(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 relative2 = path.relative(root, file);
+        return relative2 && !relative2.startsWith("..") && !path.isAbsolute(relative2);
+      }) ?? roots[0];
+      await this.loadFile(file, baseDir);
+    }
+    console.log(`[Mally] Auto-discovered ${candidateFiles} candidate file(s), loaded ${this.commands.size} command(s)`);
+  }
+  getDefaultAutoDiscoveryPatterns() {
+    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("mally:command");
+    } catch {
+      return true;
+    }
+  }
+  /**
+   * Register a command instance
+   */
+  register(instance, metadata, classConstructor, methodName) {
+    const name = metadata.name.toLowerCase();
+    if (this.commands.has(name)) {
+      console.warn(`[Mally] 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(`[Mally] 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 commands grouped by category
+   */
+  getByCategory() {
+    const categories = /* @__PURE__ */ 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.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("mally:command:guards", commandClass) || [];
+    for (const GuardClass of guards) {
+      const guardInstance = new GuardClass();
+      if (typeof guardInstance.run !== "function") {
+        console.error(
+          `[Mally] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a run() method.`
+        );
+        process.exit(1);
+      }
+      if (typeof guardInstance.guardFail !== "function") {
+        console.error(
+          `[Mally] FATAL: Guard "${GuardClass.name}" on command "${commandName}" does not have a guardFail() method.`
+        );
+        console.error(`[Mally] 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(`[Mally] Failed to load command file: ${filePath}`, error);
+    }
+  }
+  registerStoatClassCommands(stoatClass, instance, filePath, baseDir) {
+    const simpleCommands = getSimpleCommands(stoatClass);
+    const category = this.getCategoryFromPath(filePath, baseDir);
+    if (simpleCommands.length === 0) {
+      console.warn(
+        `[Mally] Class ${stoatClass.name} is decorated with @Stoat but has no @SimpleCommand methods. Skipping...`
+      );
+      this.processedStoatClasses.add(stoatClass);
+      return;
+    }
+    for (const cmdDef of simpleCommands) {
+      const method = instance[cmdDef.methodName];
+      if (typeof method !== "function") {
+        console.warn(`[Mally] 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);
+    }
+    this.processedStoatClasses.add(stoatClass);
+  }
+  /**
+   * Derive category from file path relative to base directory
+   */
+  getCategoryFromPath(filePath, baseDir) {
+    const relative2 = path.relative(baseDir, filePath);
+    const parts = relative2.split(path.sep);
+    if (parts.length > 1) {
+      return parts[0];
+    }
+    return void 0;
+  }
+};
+_CommandRegistry.DEFAULT_AUTO_DISCOVERY_IGNORES = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/*.d.ts",
+  "**/*.test.*",
+  "**/*.spec.*"
+];
+var CommandRegistry = _CommandRegistry;
+
+// src/handler.ts
+import "reflect-metadata";
+var MallyHandler = class {
+  constructor(options) {
+    this.cooldowns = /* @__PURE__ */ new Map();
+    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.disableMentionPrefix = options.disableMentionPrefix ?? false;
+  }
+  /**
+   * Initialize the handler - load all commands
+   */
+  async init() {
+    if (this.commandsDir) {
+      await this.registry.loadFromDirectory(this.commandsDir);
+      return;
+    }
+    await this.registry.autoDiscover(this.discoveryOptions);
+  }
+  /**
+   * Parse a raw message into command context
+   */
+  async parseMessage(rawContent, message, meta) {
+    const prefix = await this.resolvePrefix(meta.serverId);
+    let usedPrefix = prefix;
+    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*/);
+      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;
+    }
+    return {
+      client: this.client,
+      content: rawContent,
+      authorId: meta.authorId,
+      channelId: meta.channelId,
+      serverId: meta.serverId,
+      args,
+      prefix: usedPrefix,
+      commandName: commandName.toLowerCase(),
+      reply: meta.reply,
+      message
+    };
+  }
+  /**
+   * 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) {
+      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) => {
+      await message.channel.sendMessage(content);
+    };
+    return this.handleMessage(rawContent, message, {
+      authorId,
+      channelId,
+      serverId,
+      reply
+    });
+  }
+  /**
+   * 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 false;
+    }
+    return this.execute(ctx);
+  }
+  /**
+   * Execute a command with the given context
+   */
+  async execute(ctx) {
+    const registered = this.registry.get(ctx.commandName);
+    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;
+    }
+    const guards = Reflect.getMetadata("mally:command:guards", classConstructor) || [];
+    for (const guardClass of guards) {
+      const guardInstance = new guardClass();
+      if (typeof guardInstance.run === "function") {
+        const guardResult = await guardInstance.run(ctx);
+        if (!guardResult) {
+          if (typeof guardInstance.guardFail === "function") {
+            await guardInstance.guardFail(ctx);
+          } else {
+            console.error("[Mally] Guard check failed but no guardFail method defined on", guardClass.name);
+          }
+          return false;
+        }
+      }
+    }
+    if (!this.checkCooldown(ctx.authorId, metadata)) {
+      const remaining = this.getRemainingCooldown(ctx.authorId, metadata);
+      if (typeof instance.onCooldown === "function") {
+        await instance.onCooldown(ctx, remaining);
+      } else {
+        await ctx.reply(`Please wait ${(remaining / 1e3).toFixed(1)} seconds before using this command again.`);
+      }
+      return false;
+    }
+    try {
+      await instance[methodName](ctx);
+      if (metadata.cooldown > 0) {
+        this.setCooldown(ctx.authorId, metadata);
+      }
+      return true;
+    } catch (error) {
+      if (typeof instance.onError === "function") {
+        await instance.onError(ctx, error);
+      } else {
+        console.error(`[Mally] Error in command ${metadata.name}:`, error);
+        await ctx.reply(`An error occurred: ${error.message}`);
+      }
+      return false;
+    }
+  }
+  /**
+   * Get the command registry
+   */
+  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();
+    this.cooldowns.clear();
+    if (this.commandsDir) {
+      await this.registry.loadFromDirectory(this.commandsDir);
+      return;
+    }
+    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;
+  }
+  /**
+   * Check if user is on cooldown
+   */
+  checkCooldown(userId, metadata) {
+    if (metadata.cooldown <= 0) return true;
+    const commandCooldowns = this.cooldowns.get(metadata.name);
+    if (!commandCooldowns) return true;
+    const userCooldown = commandCooldowns.get(userId);
+    if (!userCooldown) return true;
+    return Date.now() >= userCooldown;
+  }
+  /**
+   * Get remaining cooldown time in ms
+   */
+  getRemainingCooldown(userId, metadata) {
+    const commandCooldowns = this.cooldowns.get(metadata.name);
+    if (!commandCooldowns) return 0;
+    const userCooldown = commandCooldowns.get(userId);
+    if (!userCooldown) return 0;
+    return Math.max(0, userCooldown - Date.now());
+  }
+  /**
+   * Set cooldown for a user
+   */
+  setCooldown(userId, metadata) {
+    if (!this.cooldowns.has(metadata.name)) {
+      this.cooldowns.set(metadata.name, /* @__PURE__ */ new Map());
+    }
+    const commandCooldowns = this.cooldowns.get(metadata.name);
+    commandCooldowns.set(userId, Date.now() + metadata.cooldown);
+  }
+};
+export {
+  CommandRegistry,
+  Guard,
+  METADATA_KEYS,
+  MallyHandler,
+  SimpleCommand,
+  Stoat,
+  buildSimpleCommandMetadata,
+  getGuards,
+  getSimpleCommands,
+  isStoatClass
+};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "stoatx",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A high-performance, decorator-based command handler for the Stoat ecosystem.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Arsabutispik/stoatx"
+    "url": "git+https://github.com/stoatx-ts/stoatx.git"
   },
+  "bugs": {
+    "url": "https://github.com/stoatx-ts/stoatx/issues"
+  },
+  "homepage": "https://github.com/stoatx-ts/stoatx#readme",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",