@marshmallow-stoat/mally 0.1.0

package/dist/index.mjs

@@ -0,0 +1,610 @@
+// src/types.ts
+var BaseCommand = class {
+  /**
+   * Optional: Called when an error occurs during command execution.
+   * Override this method to provide custom error handling.
+   */
+  async onError(ctx, error) {
+    await ctx.reply(`An error occurred: ${error.message}`);
+  }
+};
+
+// src/decorators/Stoat.ts
+import "reflect-metadata";
+
+// src/decorators/keys.ts
+var METADATA_KEYS = {
+  COMMAND_OPTIONS: /* @__PURE__ */ Symbol("mally:command:options"),
+  IS_COMMAND: /* @__PURE__ */ Symbol("mally:command:isCommand"),
+  IS_STOAT_CLASS: /* @__PURE__ */ Symbol("mally:stoat:isClass"),
+  SIMPLE_COMMANDS: /* @__PURE__ */ Symbol("mally:stoat:simpleCommands"),
+  GUARDS: "mally:command:guards"
+};
+
+// src/decorators/Stoat.ts
+function Stoat() {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.IS_STOAT_CLASS, true, 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/Command.ts
+import "reflect-metadata";
+function Command(options = {}) {
+  return (target) => {
+    Reflect.defineMetadata(METADATA_KEYS.IS_COMMAND, true, target);
+    Reflect.defineMetadata(METADATA_KEYS.COMMAND_OPTIONS, options, target);
+  };
+}
+function isCommand(target) {
+  return Reflect.getMetadata(METADATA_KEYS.IS_COMMAND, target) === true;
+}
+function getCommandOptions(target) {
+  return Reflect.getMetadata(METADATA_KEYS.COMMAND_OPTIONS, target);
+}
+function buildCommandMetadata(target, options, category) {
+  const className = target.name;
+  const derivedName = className.replace(/Command$/i, "").toLowerCase();
+  return {
+    name: options.name ?? derivedName,
+    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/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 { pathToFileURL } from "url";
+import { glob } from "tinyglobby";
+var CommandRegistry = class {
+  constructor(extensions = [".js", ".ts"]) {
+    this.commands = /* @__PURE__ */ new Map();
+    this.aliases = /* @__PURE__ */ new Map();
+    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)`);
+  }
+  /**
+   * 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);
+    if (!methodName) {
+      this.validateCooldown(instance, metadata);
+    }
+    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();
+  }
+  /**
+   * 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);
+      }
+    }
+  }
+  /**
+   * Validate that commands with cooldowns implement the onCooldown method
+   * @param instance
+   * @param metadata
+   * @private
+   */
+  validateCooldown(instance, metadata) {
+    if (metadata.cooldown > 0 && typeof instance.onCooldown !== "function") {
+      console.error(
+        `[Mally] FATAL: Command "${metadata.name}" has a cooldown of ${metadata.cooldown}ms but does not implement onCooldown() method.`
+      );
+      console.error(
+        `[Mally] Commands with cooldowns must implement onCooldown(ctx, remaining) to handle cooldown messages.`
+      );
+      process.exit(1);
+    }
+  }
+  /**
+   * Load commands from a single file
+   */
+  async loadFile(filePath, baseDir) {
+    try {
+      const fileUrl = pathToFileURL(filePath).href;
+      const module = await import(fileUrl);
+      for (const exportKey of Object.keys(module)) {
+        const exported = module[exportKey];
+        if (typeof exported !== "function") {
+          continue;
+        }
+        if (isStoatClass(exported)) {
+          const instance2 = new exported();
+          const simpleCommands = getSimpleCommands(exported);
+          const category2 = this.getCategoryFromPath(filePath, baseDir);
+          if (simpleCommands.length === 0) {
+            console.warn(
+              `[Mally] Class ${exported.name} is decorated with @Stoat but has no @SimpleCommand methods. Skipping...`
+            );
+            continue;
+          }
+          for (const cmdDef of simpleCommands) {
+            const method = instance2[cmdDef.methodName];
+            if (typeof method !== "function") {
+              console.warn(`[Mally] Method ${cmdDef.methodName} not found on ${exported.name}. Skipping...`);
+              continue;
+            }
+            const metadata2 = buildSimpleCommandMetadata(cmdDef.options, cmdDef.methodName, category2);
+            this.register(instance2, metadata2, exported, cmdDef.methodName);
+          }
+          continue;
+        }
+        if (!isCommand(exported)) {
+          continue;
+        }
+        const options = getCommandOptions(exported);
+        if (!options) continue;
+        const instance = new exported();
+        if (typeof instance.run !== "function") {
+          console.warn(
+            `[Mally] Class ${exported.name} is decorated with @Command but does not implement run() method. Skipping...`
+          );
+          continue;
+        }
+        const category = this.getCategoryFromPath(filePath, baseDir);
+        const metadata = buildCommandMetadata(exported, options, category);
+        instance.metadata = metadata;
+        this.register(instance, metadata, exported);
+      }
+    } catch (error) {
+      console.error(`[Mally] Failed to load command file: ${filePath}`, error);
+    }
+  }
+  /**
+   * 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;
+  }
+};
+
+// 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.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() {
+    await this.registry.loadFromDirectory(this.commandsDir);
+  }
+  /**
+   * 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 {
+      if (methodName) {
+        await instance[methodName](ctx);
+      } else {
+        await instance.run(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();
+    await this.registry.loadFromDirectory(this.commandsDir);
+  }
+  /**
+   * 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 {
+  BaseCommand,
+  Command,
+  CommandRegistry,
+  Guard,
+  METADATA_KEYS,
+  MallyHandler,
+  SimpleCommand,
+  Stoat,
+  buildCommandMetadata,
+  buildSimpleCommandMetadata,
+  getCommandOptions,
+  getGuards,
+  getSimpleCommands,
+  isCommand,
+  isStoatClass
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@marshmallow-stoat/mally",
+  "version": "0.1.0",
+  "description": "A high-performance, decorator-based command handler for the Stoat ecosystem.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "stoat.js": "^7.3.6",
+    "tinyglobby": "^0.2.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "reflect-metadata": "^0.2.0"
+  }
+}