meocord 3.0.0 → 3.2.0

package/dist/types/decorator/index.d.ts

@@ -1,6 +1,6 @@
+import { BuildableCommandType, CommandBuilderBase, CommandBuilderConstructor, CommandInteractionType, ReactionHandlerOptions, AutocompleteMetadata, CommandMetadata, GuardInterface } from '../interface/index.js';
+import { AutocompleteInteraction, OmitPartialGroupDMChannel, Message, MessageReaction, PartialMessageReaction, ClientOptions, ActivityOptions } from 'discord.js';
 import { CommandType } from '../enum/index.js';
-import { SlashCommandBuilder, SlashCommandSubcommandsOnlyBuilder, ContextMenuCommandBuilder, ButtonInteraction, StringSelectMenuInteraction, ChatInputCommandInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, ModalSubmitInteraction, OmitPartialGroupDMChannel, Message, MessageReaction, PartialMessageReaction, ClientOptions, ActivityOptions } from 'discord.js';
-import { ReactionHandlerOptions, GuardInterface } from '../interface/index.js';
 import { ServiceIdentifier } from 'inversify';
 import 'webpack';
 
@@ -29,44 +29,6 @@ import 'webpack';
  */
 declare function Service<T>(): (target: new (...args: any[]) => T) => void;
 
-/**
- * MeoCord Framework
- * Copyright (c) 2025 Ukasyah Rahmatullah Zada
- * SPDX-License-Identifier: MIT
- */
-
-/**
- * Base interface for a command builder.
- */
-interface CommandBuilderBase<T extends CommandType.SLASH | CommandType.CONTEXT_MENU = CommandType.SLASH | CommandType.CONTEXT_MENU> {
-    /**
-     * Builds the command structure using the specified command name.
-     *
-     * @param commandName - The name of the command.
-     * @returns A SlashCommandBuilder or ContextMenuCommandBuilder instance.
-     */
-    build: (commandName: string) => T extends CommandType.SLASH ? SlashCommandBuilder | SlashCommandSubcommandsOnlyBuilder : T extends CommandType.CONTEXT_MENU ? ContextMenuCommandBuilder : never;
-}
-type CommandBuilderConstructor<T extends CommandType.SLASH | CommandType.CONTEXT_MENU> = new () => CommandBuilderBase<T>;
-/**
- * Command metadata describing a registered command method.
- */
-interface CommandMetadata<T extends string = string> {
-    methodName: string;
-    builder: ReturnType<CommandBuilderBase['build']> | undefined;
-    type: CommandType;
-    regex?: RegExp;
-    dynamicParams?: T[];
-    /**
-     * How specific this pattern is; higher wins when more than one route matches the
-     * same customId. A greedy parameter can overlap a more literal sibling —
-     * `gi-profile-{uuid:*}-{uid}` also matches an id meant for
-     * `gi-profile-summary-{ownerId}-{uid}` — so dispatch cannot rely on declaration order.
-     */
-    specificity?: number;
-}
-type CommandInteractionType<CBC extends CommandType.SLASH | CommandType.CONTEXT_MENU, T extends CommandBuilderConstructor<CBC> | CommandType> = T extends CommandType.BUTTON ? ButtonInteraction : T extends CommandType.SELECT_MENU ? StringSelectMenuInteraction : T extends CommandBuilderConstructor<CommandType.SLASH> ? ChatInputCommandInteraction : T extends CommandBuilderConstructor<CommandType.CONTEXT_MENU> ? UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction : T extends CommandType.MODAL_SUBMIT ? ModalSubmitInteraction : never;
-
 /**
  * MeoCord Framework
  * Copyright (c) 2025 Ukasyah Rahmatullah Zada
@@ -91,7 +53,7 @@ type CommandInteractionType<CBC extends CommandType.SLASH | CommandType.CONTEXT_
  * @returns A decorator function that makes the target class injectable
  *          and assigns the `commandType` metadata.
  */
-declare function CommandBuilder<T extends CommandType.SLASH | CommandType.CONTEXT_MENU>(commandType: T): (target: new () => CommandBuilderBase<T>) => void;
+declare function CommandBuilder<T extends BuildableCommandType>(commandType: T): (target: new () => CommandBuilderBase<T>) => void;
 
 /**
  * MeoCord Framework
@@ -162,8 +124,13 @@ declare const PARAM_SEPARATOR = "/";
 /**
  * Decorator to register command methods in a controller.
  *
- * @param commandName - The name or pattern of the command.
- * @param builderOrType - A command builder class or a command type from `CommandType`.
+ * @param commandName - What the command is addressed by. Commands registered with
+ *   Discord use their name, and a subcommand its full path — `settings notify email`,
+ *   parts separated by a space, the way Discord displays it. Components use a customId
+ *   pattern, where `{name}` captures one `/`-separated segment.
+ * @param builderOrType - A command builder class, or a `CommandType` for a handler that
+ *   registers nothing of its own: every component, and every subcommand of a command
+ *   whose builder already describes it.
  *
  * @example
  * ```typescript
@@ -172,13 +139,23 @@ declare const PARAM_SEPARATOR = "/";
  *   await interaction.reply('This is the help command!')
  * }
  *
- * @Command('stats-{id}', CommandType.BUTTON)
- * public async handleStats(message: ButtonInteraction, { id }) {
- *   await message.reply(`Fetching stats for ID: ${id}`);
+ * @Command('settings notify email', CommandType.SLASH)
+ * public async handleNotifyEmail(interaction: ChatInputCommandInteraction, { enabled }) {
+ *   await interaction.reply(`Email notifications ${enabled ? 'on' : 'off'}`)
+ * }
+ *
+ * @Command('stats/{id}', CommandType.BUTTON)
+ * public async handleStats(interaction: ButtonInteraction, { id }) {
+ *   await interaction.reply(`Fetching stats for ID: ${id}`);
+ * }
+ *
+ * @Command('assign/{taskId}', CommandType.USER_SELECT_MENU)
+ * public async handleAssign(interaction: UserSelectMenuInteraction, { taskId }) {
+ *   await interaction.reply(`Assigned ${interaction.users.size} user(s) to ${taskId}`)
  * }
  * ```
  */
-declare function Command<CBC extends CommandType.SLASH | CommandType.CONTEXT_MENU, T extends CommandBuilderConstructor<CBC> | CommandType>(commandName: string, builderOrType: T): <P extends Record<string, any>, R extends Promise<void> | void>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<(interaction: CommandInteractionType<CBC, T>, params: P) => R> | TypedPropertyDescriptor<(interaction: CommandInteractionType<CBC, T>) => R>) => void;
+declare function Command<CBC extends BuildableCommandType, T extends CommandBuilderConstructor<CBC> | CommandType>(commandName: string, builderOrType: T): <P extends Record<string, any>, R extends Promise<void> | void>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<(interaction: CommandInteractionType<CBC, T>, params: P) => R> | TypedPropertyDescriptor<(interaction: CommandInteractionType<CBC, T>) => R>) => void;
 /**
  * Retrieves the command map for a given controller.
  *
@@ -186,6 +163,41 @@ declare function Command<CBC extends CommandType.SLASH | CommandType.CONTEXT_MEN
  * @returns A record containing command metadata indexed by command names.
  */
 declare function getCommandMap<T extends string>(controller: any): Record<string, CommandMetadata<T>[]>;
+/**
+ * Decorator to register an autocomplete handler for a chat input command's option.
+ *
+ * Autocomplete is a separate interaction from the command it belongs to, and Discord
+ * sends it while the user is still typing. It is not a `@Command`: nothing is
+ * registered for it — the option's own `setAutocomplete(true)` is what turns it on —
+ * and it is answered with `interaction.respond()` rather than a reply. Leaving it
+ * unhandled is not silent to the user: the client shows a loading state until the
+ * three-second window closes.
+ *
+ * @param commandPath - The command to complete, e.g. `settings` or `settings notify email`
+ *   for a subcommand. Parts are separated by a single space, as Discord displays them.
+ * @param optionName - The option to complete. Omit to handle every option of the command,
+ *   branching on `interaction.options.getFocused(true)`.
+ *
+ * @example
+ * ```typescript
+ * @Autocomplete('search', 'query')
+ * async completeQuery(interaction: AutocompleteInteraction) {
+ *   const { value } = interaction.options.getFocused(true)
+ *   await interaction.respond(this.search(value).map(name => ({ name, value: name })))
+ * }
+ * ```
+ */
+declare function Autocomplete<R extends void | Promise<void>>(commandPath: string, optionName?: string): <P extends Record<string, any>>(target: object, propertyKey: string, _descriptor: TypedPropertyDescriptor<(interaction: AutocompleteInteraction, params: P) => R> | TypedPropertyDescriptor<(interaction: AutocompleteInteraction) => R>) => void;
+/**
+ * Retrieves autocomplete handler metadata from a given controller.
+ *
+ * Handlers naming an option come first, so a command-wide handler acts as the fallback
+ * for options no specific handler claimed rather than shadowing them by declaration order.
+ *
+ * @param controller - The controller class instance.
+ * @returns The registered autocomplete handlers, most specific first.
+ */
+declare function getAutocompleteHandlers(controller: any): AutocompleteMetadata[];
 /**
  * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
  *
@@ -283,7 +295,7 @@ interface GuardWithParams {
  * @example
  * ```typescript
  * // Method-level usage
- * @Command('profile-{id}', CommandType.BUTTON)
+ * @Command('profile/{id}', CommandType.BUTTON)
  * @UseGuard(
  *   { provide: RateLimiterGuard, params: { limit: 2, window: 3000 } },
  *   ButtonInteractionGuard
@@ -355,4 +367,4 @@ declare function MeoCord(options: {
     services?: ServiceIdentifier[];
 }): (target: any) => void;
 
-export { Command, CommandBuilder, Controller, Guard, MeoCord, MessageHandler, PARAM_SEPARATOR, ReactionHandler, Service, UseGuard, findAmbiguousRoutes, getCommandMap, getMessageHandlers, getReactionHandlers };
+export { Autocomplete, Command, CommandBuilder, Controller, Guard, MeoCord, MessageHandler, PARAM_SEPARATOR, ReactionHandler, Service, UseGuard, findAmbiguousRoutes, getAutocompleteHandlers, getCommandMap, getMessageHandlers, getReactionHandlers };

package/dist/types/enum/index.d.ts

@@ -1,4 +1,4 @@
-export { C as CommandType, R as ReactionHandlerAction } from '../controller.enum-QA-IuReF.js';
+export { C as CommandType, R as ReactionHandlerAction } from '../controller.enum-DYfhYaat.js';
 
 /**
  * MeoCord Framework

package/dist/types/interface/index.d.ts

@@ -1,6 +1,92 @@
-import { User, PartialUser, BaseInteraction, Message, MessageReaction } from 'discord.js';
+import { SlashCommandBuilder, SlashCommandSubcommandsOnlyBuilder, ContextMenuCommandBuilder, RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody, ChatInputCommandInteraction, UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction, PrimaryEntryPointCommandInteraction, ButtonInteraction, StringSelectMenuInteraction, UserSelectMenuInteraction, RoleSelectMenuInteraction, MentionableSelectMenuInteraction, ChannelSelectMenuInteraction, ModalSubmitInteraction, User, PartialUser, BaseInteraction, Message, MessageReaction } from 'discord.js';
 import { Configuration } from 'webpack';
-import { ReactionHandlerAction } from '../enum/index.js';
+import { CommandType, ReactionHandlerAction } from '../enum/index.js';
+
+/**
+ * MeoCord Framework
+ * Copyright (c) 2025 Ukasyah Rahmatullah Zada
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * The command types that are registered with Discord, and so need a builder.
+ *
+ * Components are addressed by a customId the application makes up, so they have
+ * nothing to register; these three are published through `application.commands.set`.
+ */
+type BuildableCommandType = CommandType.SLASH | CommandType.CONTEXT_MENU | CommandType.PRIMARY_ENTRY_POINT;
+/**
+ * The body an entry point command is registered with.
+ *
+ * `description` is added back on top of the discord-api-types body: that type omits it
+ * from every non-chat-input command, but the API accepts one for entry point commands
+ * — Discord's own default activity command ships with it set.
+ */
+type PrimaryEntryPointCommandData = RESTPostAPIPrimaryEntryPointApplicationCommandJSONBody & {
+    description?: string;
+};
+/**
+ * The payload `build()` returns for a given command type.
+ *
+ * `PRIMARY_ENTRY_POINT` yields a raw REST body rather than a builder because
+ * `@discordjs/builders` ships none for it; `ApplicationCommandManager#set` accepts the
+ * JSON body directly, so nothing is lost.
+ */
+type CommandBuildResult<T extends BuildableCommandType> = T extends CommandType.SLASH ? SlashCommandBuilder | SlashCommandSubcommandsOnlyBuilder : T extends CommandType.CONTEXT_MENU ? ContextMenuCommandBuilder : T extends CommandType.PRIMARY_ENTRY_POINT ? PrimaryEntryPointCommandData : never;
+/**
+ * Base interface for a command builder.
+ */
+interface CommandBuilderBase<T extends BuildableCommandType = BuildableCommandType> {
+    /**
+     * Builds the command structure using the specified command name.
+     *
+     * @param commandName - The name of the command.
+     * @returns A builder instance, or a raw command body for entry point commands.
+     */
+    build: (commandName: string) => CommandBuildResult<T>;
+}
+type CommandBuilderConstructor<T extends BuildableCommandType> = new () => CommandBuilderBase<T>;
+/**
+ * Command metadata describing a registered command method.
+ */
+interface CommandMetadata<T extends string = string> {
+    methodName: string;
+    builder: ReturnType<CommandBuilderBase['build']> | undefined;
+    type: CommandType;
+    regex?: RegExp;
+    dynamicParams?: T[];
+    /**
+     * How specific this pattern is; higher wins when more than one route matches the
+     * same customId. A parameter takes whatever fills its segment, so a broad pattern can
+     * also match an id a more literal sibling owns — `gi-profile/{uuid}/{uid}` matches
+     * `gi-profile/summary/123/456` just as `gi-profile/summary/{ownerId}/{uid}` does — and
+     * ranking is what settles it, since declaration order would make the winner depend on
+     * file layout.
+     */
+    specificity?: number;
+}
+/** Metadata describing one `@Autocomplete` handler. */
+interface AutocompleteMetadata {
+    /** The command path the handler serves, e.g. `settings` or `settings notify email`. */
+    commandPath: string;
+    /** The option it completes, or `undefined` to complete every option of that command. */
+    optionName?: string;
+    methodName: string;
+}
+/** The interaction class each non-buildable command type hands to its handler. */
+interface ComponentInteractionMap {
+    [CommandType.BUTTON]: ButtonInteraction;
+    [CommandType.SELECT_MENU]: StringSelectMenuInteraction;
+    [CommandType.USER_SELECT_MENU]: UserSelectMenuInteraction;
+    [CommandType.ROLE_SELECT_MENU]: RoleSelectMenuInteraction;
+    [CommandType.MENTIONABLE_SELECT_MENU]: MentionableSelectMenuInteraction;
+    [CommandType.CHANNEL_SELECT_MENU]: ChannelSelectMenuInteraction;
+    [CommandType.MODAL_SUBMIT]: ModalSubmitInteraction;
+    [CommandType.SLASH]: ChatInputCommandInteraction;
+    [CommandType.CONTEXT_MENU]: UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction;
+    [CommandType.PRIMARY_ENTRY_POINT]: PrimaryEntryPointCommandInteraction;
+}
+type CommandInteractionType<CBC extends BuildableCommandType, T extends CommandBuilderConstructor<CBC> | CommandType> = T extends CommandBuilderConstructor<CommandType.SLASH> ? ChatInputCommandInteraction : T extends CommandBuilderConstructor<CommandType.CONTEXT_MENU> ? UserContextMenuCommandInteraction | MessageContextMenuCommandInteraction : T extends CommandBuilderConstructor<CommandType.PRIMARY_ENTRY_POINT> ? PrimaryEntryPointCommandInteraction : T extends keyof ComponentInteractionMap ? ComponentInteractionMap[T] : never;
 
 /**
  * MeoCord Framework
@@ -92,4 +178,4 @@ interface MeoCordConfig {
     webpack?: (config: MeoCordWebpackConfig) => MeoCordWebpackConfig | undefined;
 }
 
-export type { GuardInterface, MeoCordConfig, MeoCordWebpackConfig, ReactionHandlerOptions };
+export type { AutocompleteMetadata, BuildableCommandType, CommandBuildResult, CommandBuilderBase, CommandBuilderConstructor, CommandInteractionType, CommandMetadata, GuardInterface, MeoCordConfig, MeoCordWebpackConfig, ReactionHandlerOptions };

package/dist/types/testing/index.d.ts

@@ -2,7 +2,7 @@ import { ServiceIdentifier, Container } from 'inversify';
 import { GuardInterface } from '../interface/index.js';
 import { CacheType, CommandInteractionOptionResolver, Channel, Client, Guild, Message, User } from 'discord.js';
 import 'webpack';
-import '../controller.enum-QA-IuReF.js';
+import '../controller.enum-DYfhYaat.js';
 
 /**
  * MeoCord Framework
@@ -277,30 +277,12 @@ declare function createMockMessage(): DeepMocked<Message>;
 interface ChatInputOptions {
     subcommandGroup?: string | null;
     subcommand?: string | null;
+    /** The option the user is currently typing, for autocomplete interactions. */
+    focused?: string | null;
     [name: string]: string | number | boolean | {
         id: string;
     } | null | undefined;
 }
-/**
- * Builds a typed options resolver from a plain record. Mirrors how the real
- * `CommandInteractionOptionResolver` works: declare what options the command
- * was invoked with, and the resolver finds them by name.
- *
- * All explicit methods are mock functions — override per test with `.mockReturnValue()`.
- * Methods not listed (e.g. `getAttachment`) are auto-stubbed by the Proxy.
- *
- * @example
- * ```ts
- * const interaction = createMockInteraction(ChatInputCommandInteraction)
- * interaction.options = createChatInputOptions({
- *   subcommandGroup: 'daily',
- *   subcommand: 'notes',
- *   uid: 12345678,
- * })
- * interaction.options.getSubcommand()  // → 'notes'
- * interaction.options.getNumber('uid') // → 12345678
- * ```
- */
 declare function createChatInputOptions<Cached extends CacheType = any>(opts?: ChatInputOptions): DeepMocked<CommandInteractionOptionResolver<Cached>>;
 
 export { MeoCordTestingModule, TestingModule, TestingModuleBuilder, createChatInputOptions, createMock, createMockChannel, createMockClient, createMockFn, createMockGuild, createMockInteraction, createMockMessage, createMockUser, isMockFunction };

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "meocord",
   "description": "Decorator-based Discord bot framework built on discord.js. Brings NestJS-style controllers, dependency injection, guards, and testing utilities to bot development — with a full CLI and TypeScript-first design.",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "lint": "eslint --fix . && tsc --noEmit && tsc --noEmit --project tsconfig.test.json",
+    "format": "prettier --write \"**/*.md\" \"src/bin/app-template/**/*.template\"",
+    "format:check": "prettier --check \"**/*.md\" \"src/bin/app-template/**/*.template\"",
+    "lint": "bun run format && eslint --fix . && tsc --noEmit && tsc --noEmit --project tsconfig.test.json && tsc --noEmit --project tsconfig.eslint.json",
     "build": "rm -rf ./dist && rollup -c",
     "prepare": "husky",
     "test": "vitest run",
+    "verify:generated": "bun scripts/verify-generated.ts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:typecheck": "tsc --noEmit --project tsconfig.test.json"
@@ -75,16 +78,14 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@swc/core": "1.15.47",
+    "@swc/core": "1.16.1",
     "chalk": "^6.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
-    "dayjs": "^1.11.21",
-    "dotenv": "^17.4.2",
+    "dayjs": "^1.11.23",
     "inversify": "^8.2.3",
     "jiti": "^2.7.0",
     "lodash-es": "^4.18.1",
-    "nodemon": "^3.1.14",
     "reflect-metadata": "^0.2.2",
     "simple-git": "^3.36.0",
     "swc-loader": "^0.2.7",
@@ -100,14 +101,13 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-swc": "^0.4.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/lodash-es": "^4.17.12",
     "@types/webpack-node-externals": "^3.0.4",
     "@typescript-eslint/parser": "^8.67.0",
     "discord.js": "^14.27.0",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-headers": "^1.3.4",
     "eslint-plugin-import-x": "^4.17.1",
@@ -116,16 +116,15 @@
     "globals": "^17.11.0",
     "husky": "^9.1.7",
     "prettier": "^3.9.6",
-    "rollup": "^4.62.4",
+    "rollup": "^4.62.5",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.5.1",
     "semantic-release": "^25.0.9",
-    "ts-node": "^10.9.2",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.67.0",
-    "@vitest/coverage-istanbul": "^4.1.10",
+    "@vitest/coverage-istanbul": "^4.1.11",
     "unplugin-swc": "^1.5.11",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "discord.js": "^14.26.4",