meocord 3.0.0 → 3.2.0

package/dist/esm/testing/mock-interaction.js

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { createMockFn } from './mock-fn.js';
-import { InteractionType, ComponentType, ApplicationCommandType, CommandInteractionOptionResolver, GuildMessageManager, ThreadManager, DMMessageManager, MessageManager, ThreadMemberManager, Client, ApplicationCommandManager, UserManager, ChannelManager, GuildManager, ClientUser, Guild, GuildMemberManager, GuildChannelManager, RoleManager, GuildBanManager, Message, User, GuildMember, TextChannel, ThreadChannel, MessageMentions } from 'discord.js';
+import { InteractionType, ComponentType, ApplicationCommandType, CommandInteractionOptionResolver, GuildMessageManager, ThreadManager, DMMessageManager, MessageManager, ThreadMemberManager, Client, ApplicationCommandManager, UserManager, ChannelManager, GuildManager, ClientUser, Guild, GuildMemberManager, GuildChannelManager, RoleManager, GuildBanManager, Message, User, GuildMember, TextChannel, ThreadChannel, MessageMentions, ApplicationCommandOptionType, Role, BaseChannel, Attachment } from 'discord.js';
 
 // ---------------------------------------------------------------------------
 // stubDeep — Proxy that auto-creates a mock fn on any property access
@@ -140,7 +140,9 @@ const TYPE_GUARD_METHODS = [
     'isMentionableSelectMenu',
     'isChannelSelectMenu',
     'isAnySelectMenu',
-    'isSelectMenu',
+    // `isSelectMenu` is intentionally absent: discord.js deprecated it in favour of
+    // `isStringSelectMenu`, and wiring it here would emit a deprecation warning on every
+    // mock that has it on its prototype.
     'isModalSubmit',
     'isAutocomplete',
     'isRepliable'
@@ -210,9 +212,11 @@ function findPrototypeMethod(instance, name) {
         instance.ephemeral = false;
         const alreadyReplied = ()=>new Error('The reply to this interaction has already been sent or deferred.');
         const notYetReplied = (method)=>new Error(`Cannot call ${method}() before replying or deferring.`);
+        // Only `flags` is read: the `ephemeral: true` reply option is deprecated in
+        // discord.js, and honouring it here would let a test pass against a call the
+        // library has stopped supporting.
         const hasEphemeralFlag = (options)=>{
             if (!options) return false;
-            if (options.ephemeral === true) return true;
             const { flags } = options;
             if (typeof flags === 'number') return (flags & 64) !== 0;
             if (typeof flags === 'bigint') return (flags & 64n) !== 0n;
@@ -253,6 +257,17 @@ function findPrototypeMethod(instance, name) {
             }));
         }
     }
+    // Autocomplete is not repliable, but it has a response of its own: Discord accepts
+    // one `respond()` per interaction and rejects the second. Without `responded` set
+    // here it would read as an auto-stubbed object -- truthy -- and any code that checks
+    // it before answering would decide the window was already closed.
+    if (instance.type === InteractionType.ApplicationCommandAutocomplete) {
+        instance.responded = false;
+        stubs.set('respond', createMockFn(async ()=>{
+            if (instance.responded) throw new Error('The reply to this interaction has already been sent or deferred.');
+            instance.responded = true;
+        }));
+    }
     // Applied last so an explicit prop wins over the type fields and the reply
     // state machine. defineProperty rather than assignment for the same reason the
     // Proxy uses it: several of these shadow a getter-only prototype accessor.
@@ -532,7 +547,64 @@ function createMockMessage() {
  * interaction.options.getSubcommand()  // → 'notes'
  * interaction.options.getNumber('uid') // → 12345678
  * ```
- */ // `any` is the default rather than `CacheType` because TypeScript types a generic
+ */ /** The option type Discord would have sent for a given JavaScript value. */ function optionTypeOf(value) {
+    if (typeof value === 'boolean') return ApplicationCommandOptionType.Boolean;
+    if (typeof value === 'number') return ApplicationCommandOptionType.Number;
+    if (value instanceof User) return ApplicationCommandOptionType.User;
+    if (value instanceof GuildMember) return ApplicationCommandOptionType.User;
+    if (value instanceof Role) return ApplicationCommandOptionType.Role;
+    if (value instanceof BaseChannel) return ApplicationCommandOptionType.Channel;
+    if (value instanceof Attachment) return ApplicationCommandOptionType.Attachment;
+    if (typeof value === 'object' && value !== null) return ApplicationCommandOptionType.Mentionable;
+    return ApplicationCommandOptionType.String;
+}
+/**
+ * Shapes one supplied option the way the gateway sends it.
+ *
+ * An entity option arrives as a snowflake in `value` *and* as the resolved object on
+ * its own field, and code that reads only one of the two is exactly what this lets a
+ * test catch — so both are set.
+ */ function toOptionData(name, value) {
+    const type = optionTypeOf(value);
+    const isEntity = typeof value === 'object' && value !== null;
+    const option = {
+        name,
+        type,
+        value: isEntity ? value.id : value
+    };
+    if (value instanceof User) option.user = value;
+    else if (value instanceof GuildMember) option.member = value;
+    else if (value instanceof Role) option.role = value;
+    else if (value instanceof BaseChannel) option.channel = value;
+    else if (value instanceof Attachment) option.attachment = value;
+    else if (isEntity) option.user = value;
+    return option;
+}
+/**
+ * Nests the supplied options under the subcommand path they were invoked through,
+ * matching the shape Discord sends rather than a flat list.
+ */ function buildOptionData(subcommandGroup, subcommand, values) {
+    const leaves = Object.entries(values).map(([name, value])=>toOptionData(name, value));
+    if (subcommand === null) return leaves;
+    const sub = {
+        name: subcommand,
+        type: ApplicationCommandOptionType.Subcommand,
+        options: leaves
+    };
+    if (subcommandGroup === null) return [
+        sub
+    ];
+    return [
+        {
+            name: subcommandGroup,
+            type: ApplicationCommandOptionType.SubcommandGroup,
+            options: [
+                sub
+            ]
+        }
+    ];
+}
+// `any` is the default rather than `CacheType` because TypeScript types a generic
 // class's `prototype` with `any` for its parameters, and createMockInteraction infers
 // T from exactly that — `createMockInteraction(ChatInputCommandInteraction)` produces
 // an interaction whose `options` is `CommandInteractionOptionResolver<any>`. Defaulting
@@ -540,7 +612,7 @@ function createMockMessage() {
 // the target rejects, and the resolver stops being assignable to the property it exists
 // to fill. Pass Cached explicitly when the interaction under test is pinned.
 function createChatInputOptions(opts = {}) {
-    const { subcommandGroup = null, subcommand = null, ...values } = opts;
+    const { subcommandGroup = null, subcommand = null, focused = null, ...values } = opts;
     function resolveOrThrow(name, value, required) {
         if (value === null) {
             if (required === true) throw new Error(`Option "${name}" is required but was not provided.`);
@@ -571,6 +643,18 @@ function createChatInputOptions(opts = {}) {
     base.getChannel = createMockFn(getObjectOption);
     base.getMember = createMockFn(getObjectOption);
     base.getMentionable = createMockFn(getObjectOption);
+    base.getFocused = createMockFn((getFull)=>{
+        if (focused === null) throw new Error('No focused option found.');
+        const option = toOptionData(focused, values[focused] ?? null);
+        return getFull === true ? {
+            ...option,
+            focused: true
+        } : option.value;
+    });
+    // `data` is what the framework reads to build a handler's params, and it is the one
+    // part of the resolver that is not a method — so it has to be materialised here
+    // rather than auto-stubbed, or every params assertion would see an empty record.
+    base.data = buildOptionData(subcommandGroup, subcommand, values);
     return stubDeep(base);
 }
 

package/dist/esm/util/common.util.js

@@ -47,8 +47,16 @@ import chalk from 'chalk';
         await wait(100);
         process.exit(1);
     }
-    const meocordConfig = loadMeoCordConfig();
-    if (!meocordConfig?.discordToken) {
+    loadMeoCordConfig();
+}
+/**
+ * Ensures a Discord token is configured.
+ *
+ * Kept apart from {@link compileAndValidateConfig} because producing a bundle needs no
+ * credentials — only connecting to the gateway does. Requiring one to build meant a
+ * freshly created application could not be built until a token had been obtained.
+ */ async function validateDiscordToken() {
+    if (!loadMeoCordConfig()?.discordToken) {
         console.error(chalk.red('Discord token is missing!'));
         await wait(100);
         process.exit(1);
@@ -65,4 +73,4 @@ import chalk from 'chalk';
     }
 }
 
-export { compileAndValidateConfig, findModulePackageDir, setEnvironment };
+export { compileAndValidateConfig, findModulePackageDir, setEnvironment, validateDiscordToken };

package/dist/esm/util/generator-cli.util.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
 import { kebabCase, startCase, camelCase } from 'lodash-es';
@@ -67,12 +67,29 @@ const logger = new Logger('MeoCord');
  */ function generateFile(filePath, content) {
     try {
         fs.writeFileSync(filePath, content);
-        logger.log(`Guard file created at: ${path.relative(process.cwd(), filePath)}`);
-        exec(`npx eslint --fix ${filePath}`);
+        logger.log(`Created ${path.relative(process.cwd(), filePath)}`);
+        formatWithLocalESLint(filePath);
     } catch (error) {
-        logger.error(`Failed to create guard file at ${filePath}`, error);
+        logger.error(`Failed to create ${filePath}`, error);
     }
 }
+/**
+ * Formats a generated file with the project's own ESLint, when it has one.
+ *
+ * Reaching for `npx` instead would start downloading ESLint into a project that
+ * deliberately does not have it, once per generated file, with no way to see it happen —
+ * the call is not awaited. A project with its own rules still gets them applied.
+ */ function formatWithLocalESLint(filePath) {
+    const binary = path.resolve(process.cwd(), 'node_modules', '.bin', process.platform === 'win32' ? 'eslint.cmd' : 'eslint');
+    if (!fs.existsSync(binary)) return;
+    execFile(binary, [
+        '--fix',
+        filePath
+    ], ()=>{
+    // Formatting is a courtesy; a project whose rules reject the template should still
+    // end up with the file it asked for.
+    });
+}
 /**
  * Builds and returns a template string for a given class name using a specific template file.
  * @param className - The name of the class to insert into the template.

package/dist/esm/util/interaction.util.js

@@ -0,0 +1,174 @@
+import { ApplicationCommandOptionType, MessageComponentInteraction, ModalSubmitInteraction, ChannelSelectMenuInteraction, MentionableSelectMenuInteraction, RoleSelectMenuInteraction, UserSelectMenuInteraction, StringSelectMenuInteraction, ButtonInteraction, PrimaryEntryPointCommandInteraction, ContextMenuCommandInteraction, ChatInputCommandInteraction } from 'discord.js';
+import { CommandType } from '../enum/controller.enum.js';
+
+/**
+ * The discord.js class each command type is handled by.
+ *
+ * One table rather than a chain of `isButton() || isStringSelectMenu() || ...`: the
+ * registration guard in `@Command`, the dispatcher, and the type-level
+ * `CommandInteractionType` all have to agree on what a command type accepts, and a
+ * chain repeated in three files drifts the moment a fifth select menu appears. Adding
+ * a `CommandType` member without an entry here is a compile error, not a silent
+ * fall-through to "Command not found!".
+ */ const INTERACTION_MATCHERS = {
+    [CommandType.SLASH]: (interaction)=>interaction instanceof ChatInputCommandInteraction,
+    [CommandType.CONTEXT_MENU]: (interaction)=>interaction instanceof ContextMenuCommandInteraction,
+    [CommandType.PRIMARY_ENTRY_POINT]: (interaction)=>interaction instanceof PrimaryEntryPointCommandInteraction,
+    [CommandType.BUTTON]: (interaction)=>interaction instanceof ButtonInteraction,
+    [CommandType.SELECT_MENU]: (interaction)=>interaction instanceof StringSelectMenuInteraction,
+    [CommandType.USER_SELECT_MENU]: (interaction)=>interaction instanceof UserSelectMenuInteraction,
+    [CommandType.ROLE_SELECT_MENU]: (interaction)=>interaction instanceof RoleSelectMenuInteraction,
+    [CommandType.MENTIONABLE_SELECT_MENU]: (interaction)=>interaction instanceof MentionableSelectMenuInteraction,
+    [CommandType.CHANNEL_SELECT_MENU]: (interaction)=>interaction instanceof ChannelSelectMenuInteraction,
+    [CommandType.MODAL_SUBMIT]: (interaction)=>interaction instanceof ModalSubmitInteraction
+};
+/** Command types Discord identifies by a registered name rather than by a customId. */ const NAME_ROUTED_TYPES = new Set([
+    CommandType.SLASH,
+    CommandType.CONTEXT_MENU,
+    CommandType.PRIMARY_ENTRY_POINT
+]);
+/**
+ * Whether an interaction is the kind the given command type handles.
+ *
+ * @param type - The command type declared on `@Command`.
+ * @param interaction - The interaction being dispatched.
+ */ function matchesCommandType(type, interaction) {
+    const matches = INTERACTION_MATCHERS[type];
+    return matches !== undefined && matches(interaction);
+}
+/**
+ * Whether the command type is routed by matching a customId pattern.
+ *
+ * Components carry an application-defined customId and so are matched by pattern;
+ * commands carry a name Discord itself registered and are matched exactly.
+ *
+ * @param type - The command type declared on `@Command`.
+ */ function isCustomIdRouted(type) {
+    return !NAME_ROUTED_TYPES.has(type);
+}
+/**
+ * Whether an interaction carries a customId, and so can be routed by pattern.
+ *
+ * @param interaction - The interaction being dispatched.
+ */ function hasCustomId(interaction) {
+    return interaction instanceof MessageComponentInteraction || interaction instanceof ModalSubmitInteraction;
+}
+/** Separates a command from its subcommand group and subcommand in a route key. */ const COMMAND_PATH_SEPARATOR = ' ';
+/**
+ * The route keys a chat input interaction can be handled by, most specific first.
+ *
+ * Discord sends `/settings notify email` as one interaction named `settings`, so
+ * routing on `commandName` alone gives every subcommand of a command the same handler
+ * — and the framework would run whichever one was declared first. The full path is
+ * tried before the bare name so a command can either split its subcommands across
+ * methods or keep handling them in one, but never both by accident.
+ *
+ * A group is never dropped on the way down: `settings notify email` does not fall back
+ * to `settings email`, because a second group could declare its own `email` and the
+ * two would be indistinguishable.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns The keys to look up, most specific first.
+ */ function resolveCommandPaths(interaction) {
+    const { commandName } = interaction;
+    const options = interaction.options;
+    // Guarded rather than called directly: `options` is a stub on a hand-built test
+    // double, and an interaction whose command has no subcommands still has to route.
+    const group = typeof options?.getSubcommandGroup === 'function' ? options.getSubcommandGroup(false) : null;
+    const sub = typeof options?.getSubcommand === 'function' ? options.getSubcommand(false) : null;
+    const path = [
+        commandName,
+        group,
+        sub
+    ].filter((part)=>Boolean(part));
+    const full = path.join(COMMAND_PATH_SEPARATOR);
+    return full === commandName ? [
+        commandName
+    ] : [
+        full,
+        commandName
+    ];
+}
+/** Options that only wrap other options; their values live one level down. */ const NESTING_OPTION_TYPES = new Set([
+    ApplicationCommandOptionType.Subcommand,
+    ApplicationCommandOptionType.SubcommandGroup
+]);
+/**
+ * The value a handler should receive for one option.
+ *
+ * Discord sends entity options as a snowflake plus a `resolved` payload, and discord.js
+ * puts that payload on the option as `user`/`role`/`channel`/`attachment`. Passing
+ * `value` alone would hand the handler a bare id string for `@user`, forcing every
+ * handler to re-fetch what the gateway already delivered.
+ */ function resolveOptionValue(option) {
+    return option.attachment ?? option.channel ?? option.role ?? option.user ?? option.member ?? option.value;
+}
+/**
+ * Flattens a chat input interaction's options into the params record handlers receive.
+ *
+ * Subcommand and subcommand-group options are containers, not values — for
+ * `/settings notify email true` the top level holds only `notify`. Recursing past them
+ * means a subcommand handler sees `{ email: true }`, the same shape a flat command's
+ * handler sees.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns Each supplied option keyed by name, with entity options resolved.
+ */ function resolveOptionParams(interaction) {
+    const data = interaction.options?.data;
+    if (!Array.isArray(data)) return {};
+    const params = {};
+    const walk = (options)=>{
+        for (const option of options){
+            if (NESTING_OPTION_TYPES.has(option.type)) {
+                walk(option.options ?? []);
+                continue;
+            }
+            params[option.name] = resolveOptionValue(option);
+        }
+    };
+    walk(data);
+    return params;
+}
+/**
+ * The name of the option the user is currently typing, or `undefined`.
+ *
+ * `getFocused` throws when nothing is focused rather than returning null, and it is
+ * absent altogether on a hand-built test double. Neither is worth failing a dispatch
+ * over — an autocomplete with no focused option simply matches no option-specific
+ * handler.
+ *
+ * @param interaction - The autocomplete interaction being dispatched.
+ */ function focusedOptionName(interaction) {
+    if (typeof interaction.options?.getFocused !== 'function') return undefined;
+    try {
+        return interaction.options.getFocused(true)?.name;
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Identifies an interaction in a log line, by whichever field would have routed it.
+ *
+ * @param interaction - The interaction that matched no handler.
+ */ function describeInteraction(interaction) {
+    // Captured before the narrowing below: the guards cover every member of the union,
+    // so by the fallback `interaction` is `never` and nothing can be read off it.
+    const { type } = interaction;
+    if (interaction.isAutocomplete()) {
+        const path = resolveCommandPaths(interaction)[0];
+        const focused = focusedOptionName(interaction);
+        return focused === undefined ? `autocomplete for "${path}"` : `autocomplete for "${path}" option "${focused}"`;
+    }
+    if (interaction.isChatInputCommand()) {
+        return `command "${resolveCommandPaths(interaction)[0]}"`;
+    }
+    if (interaction.isContextMenuCommand() || interaction.isPrimaryEntryPointCommand()) {
+        return `command "${interaction.commandName}"`;
+    }
+    if (hasCustomId(interaction)) {
+        return `customId "${interaction.customId}"`;
+    }
+    return `interaction type ${type}`;
+}
+
+export { COMMAND_PATH_SEPARATOR, describeInteraction, focusedOptionName, hasCustomId, isCustomIdRouted, matchesCommandType, resolveCommandPaths, resolveOptionParams };

package/dist/esm/util/package-manager.util.js

@@ -6,10 +6,17 @@ const ALL_PACKAGE_MANAGERS = [
     'yarn',
     'pnpm'
 ];
-function detectInstalledPMs() {
+/**
+ * The package managers available on this machine.
+ *
+ * Each candidate is asked for its version rather than looked up with `which`: `which` is
+ * a separate binary that a minimal image need not carry, and it is absent on Windows
+ * entirely. Running the tool also answers the question actually being asked — whether it
+ * works — rather than whether something with that name sits on the path.
+ */ function detectInstalledPMs() {
     return ALL_PACKAGE_MANAGERS.filter((pm)=>{
         try {
-            execSync(`which ${pm}`, {
+            execSync(`${pm} --version`, {
                 stdio: 'ignore'
             });
             return true;

package/dist/esm/util/package-version.util.js

@@ -0,0 +1,32 @@
+import fs__default from 'node:fs';
+import path from 'node:path';
+
+/** The package this CLI ships in, which is where the walk below stops. */ const OWN_PACKAGE_NAME = 'meocord';
+/**
+ * The version recorded in the package this CLI ships in.
+ *
+ * Read at run time rather than compiled in. The release bumps the manifest after the
+ * bundle has already been built, so a version baked into the bundle is always the one
+ * from before the release that published it.
+ *
+ * The walk stops at the first manifest naming this package: the repository root when
+ * running from source, the installed package root when running from `dist`.
+ *
+ * @param startDir - Directory to walk up from.
+ * @param fallback - Returned when no manifest for this package can be read.
+ */ function resolveOwnVersion(startDir, fallback) {
+    let current = path.resolve(startDir);
+    while(true){
+        try {
+            const manifest = JSON.parse(fs__default.readFileSync(path.join(current, 'package.json'), 'utf8'));
+            if (manifest.name === OWN_PACKAGE_NAME && typeof manifest.version === 'string') return manifest.version;
+        } catch  {
+        // Nothing readable here; the next directory up may still hold the manifest.
+        }
+        const parent = path.dirname(current);
+        if (parent === current) return fallback;
+        current = parent;
+    }
+}
+
+export { resolveOwnVersion };

package/dist/esm/util/runtime.util.js

@@ -0,0 +1,72 @@
+/**
+ * MeoCord Framework
+ * Copyright (c) 2025 Ukasyah Rahmatullah Zada
+ * SPDX-License-Identifier: MIT
+ */ /**
+ * Environment variable that pins the binary the application is spawned with.
+ *
+ * An escape hatch for pinning a specific install, or for running the application under a
+ * different runtime than the CLI to compare behaviour. Unset is the normal case.
+ */ const RUNTIME_OVERRIDE_ENV = 'MEOCORD_RUNTIME';
+/**
+ * Runners that are themselves JavaScript runtimes.
+ *
+ * `npm_execpath` names the binary that launched the script. npm, pnpm and yarn set it to
+ * a `.js` file, which cannot run the application, so only the runners listed here are
+ * read as a runtime. An entry belongs here only once it has been checked against that
+ * runner's real environment, since guessing wrong means spawning something that cannot
+ * execute the bundle.
+ */ const RUNTIME_RUNNERS = new Set([
+    'bun'
+]);
+/**
+ * The runtime that launched the CLI, when the CLI is not itself running on it.
+ *
+ * `bun run` honours the bin's `#!/usr/bin/env node` shebang, so the CLI lands on node
+ * even though the user asked for bun. What they chose is still recoverable: bun sets
+ * `npm_config_user_agent` to `bun/<version> …` and `npm_execpath` to its own binary.
+ *
+ * @param env - Environment the CLI was launched with.
+ * @returns The launcher's binary, or `undefined` when it cannot run the application.
+ */ function launcherRuntime(env) {
+    const runner = env.npm_config_user_agent?.split('/')[0];
+    const launcher = env.npm_execpath?.trim();
+    if (runner === undefined || !launcher) return undefined;
+    return RUNTIME_RUNNERS.has(runner) ? launcher : undefined;
+}
+/**
+ * The binary the application should be spawned with.
+ *
+ * Follows the runtime the user chose rather than naming one. Someone who typed `bun`
+ * gets a bun process, and an image built on bun alone stays that way — pinning `node`
+ * would oblige them to install a second runtime beside the one they picked, or to
+ * remember `--bun` on every command.
+ *
+ * Preference runs from the most explicit signal to the least: an override, then the
+ * runner that launched the CLI, then the binary executing it.
+ *
+ * @param env - Environment the CLI was launched with.
+ * @param execPath - Binary executing the CLI, i.e. `process.execPath`.
+ * @returns The binary to spawn.
+ */ function resolveRuntime(env, execPath) {
+    const override = env[RUNTIME_OVERRIDE_ENV]?.trim();
+    // An override of only whitespace would spawn '' and fail with an ENOENT naming nothing,
+    // so it is treated as absent rather than passed through.
+    if (override) return override;
+    return launcherRuntime(env) ?? execPath;
+}
+/**
+ * Runs the built application directly.
+ *
+ * @param runtime - Binary to run the application with.
+ * @param mainJsPath - Absolute path to the built entry file.
+ */ function buildAppCommand(runtime, mainJsPath) {
+    return {
+        command: runtime,
+        args: [
+            mainJsPath
+        ]
+    };
+}
+
+export { RUNTIME_OVERRIDE_ENV, buildAppCommand, resolveRuntime };

package/dist/types/controller.enum-DYfhYaat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The kinds of interaction a `@Command` method can be bound to.
+ *
+ * Each member names one Discord interaction shape rather than a family of them, so a
+ * handler's parameter type follows from its command type alone. That is why the four
+ * entity select menus are separate members instead of one `SELECT_MENU`: Discord sends
+ * them as distinct component types (5-8) carrying different resolved data, and
+ * collapsing them would leave the handler with a union it has to re-narrow by hand.
+ */
+declare enum CommandType {
+    /** Chat input command, or one subcommand of it. */
+    SLASH = "SLASH",
+    /** User or message context menu command. */
+    CONTEXT_MENU = "CONTEXT_MENU",
+    /** Activity launch command (`ApplicationCommandType.PrimaryEntryPoint`). */
+    PRIMARY_ENTRY_POINT = "PRIMARY_ENTRY_POINT",
+    BUTTON = "BUTTON",
+    /** String select menu — the one whose options the application defines itself. */
+    SELECT_MENU = "SELECT_MENU",
+    USER_SELECT_MENU = "USER_SELECT_MENU",
+    ROLE_SELECT_MENU = "ROLE_SELECT_MENU",
+    MENTIONABLE_SELECT_MENU = "MENTIONABLE_SELECT_MENU",
+    CHANNEL_SELECT_MENU = "CHANNEL_SELECT_MENU",
+    MODAL_SUBMIT = "MODAL_SUBMIT"
+}
+/**
+ * Enum representing actions that can be performed on a message reaction.
+ */
+declare enum ReactionHandlerAction {
+    /** Reaction added to a message. */
+    ADD = "ADD",
+    /** Reaction removed from a message. */
+    REMOVE = "REMOVE"
+}
+
+export { CommandType as C, ReactionHandlerAction as R };

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

@@ -19,6 +19,31 @@ declare class MeoCordApp {
     private activityInterval;
     private controllerInstancesCache;
     constructor(controllerClasses: (new (...args: any[]) => any)[], container: Container, discordClient: Client, discordToken: string, activities?: ActivityOptions[] | undefined);
+    /**
+     * Runs an event handler so a failure inside it cannot take the process down.
+     *
+     * discord.js calls listeners without awaiting them, so a rejection escaping one has
+     * nothing left to settle it: Node reports an unhandled rejection, which terminates
+     * the process by default. Losing the whole bot because one reaction landed on a
+     * deleted message, or one controller could not be resolved, is a worse failure than
+     * the one that caused it -- every other user is served by the same process.
+     *
+     * Nothing is silenced. The error is logged against the event that produced it, so a
+     * genuine misconfiguration -- an unbound controller, a missing dependency -- shows
+     * up on the very first interaction rather than staying hidden.
+     *
+     * @param event - The gateway event being handled, named in the log.
+     * @param run - The handler to run.
+     */
+    private runListener;
+    /**
+     * Rotates the bot's activity.
+     *
+     * Guarded separately from {@link runListener}: this runs on a timer rather than an
+     * event, and a throw from a timer callback is an uncaught exception no listener
+     * wrapper can reach.
+     */
+    private updateActivity;
     private getInstance;
     start(): Promise<void>;
     registerCommands(): Promise<void>;
@@ -27,8 +52,8 @@ declare class MeoCordApp {
      *
      * Built once and cached, so dispatch stays a single ordered walk with an early exit
      * rather than paying to rank anything per interaction. Ordering here is what lets
-     * `gi-profile-summary-{ownerId}-{uid}` keep the ids it owns when
-     * `gi-profile-{uuid}-{uid}` would also match them — without it, the winner would be
+     * `gi-profile/summary/{ownerId}/{uid}` keep the ids it owns when
+     * `gi-profile/{uuid}/{uid}` would also match them — without it, the winner would be
      * whichever controller happened to be registered first.
      */
     private componentRoutes?;
@@ -38,12 +63,60 @@ declare class MeoCordApp {
      * refusing to start would turn a latent mis-route into an outage on upgrade.
      */
     private reportAmbiguousRoutes;
+    /**
+     * Every `@Autocomplete` handler, ordered so an option-specific handler is found
+     * before a command-wide one.
+     *
+     * Cached alongside the component table: autocomplete fires on every keystroke, and
+     * rebuilding the list per keystroke would put reflection on the hottest path the
+     * framework has.
+     */
+    private autocompleteRoutes?;
+    private getAutocompleteRoutes;
+    /**
+     * Dispatches an interaction, and makes sure a failure anywhere in that still reaches
+     * the person who triggered it.
+     *
+     * {@link executeCommand} already reports what a handler throws, but everything
+     * *before* the handler can fail too — resolving a controller through the container
+     * is the common case — and a component that fails there would otherwise look dead
+     * with nothing said to the user and nothing in the log.
+     */
     private handleInteraction;
+    private dispatchInteraction;
+    /**
+     * The names a command interaction can be handled under, most specific first.
+     *
+     * Empty for anything that is not a registered command, which is how a component
+     * whose customId matched no pattern falls through to the unmatched warning instead
+     * of being looked up under a name it does not have.
+     */
+    private resolveNameRoutes;
+    /**
+     * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it.
+     *
+     * Discord closes the window after three seconds and shows a loading state until
+     * something arrives, so an unclaimed option is answered with an empty list rather
+     * than left to time out -- a visibly empty menu is a better failure than a stuck one,
+     * and the warning says which option is missing a handler.
+     */
+    private handleAutocomplete;
+    /** Closes an autocomplete window that nothing else answered. */
+    private respondEmpty;
     /**
      * Runs a resolved command, shared by both dispatch paths so a pattern-matched
      * component and a named slash command behave identically once the route is chosen.
      */
     private executeCommand;
+    /**
+     * Tells the user something went wrong, if the interaction can still hear it.
+     *
+     * A handler that replies and *then* throws is the common shape of a failure, and
+     * replying twice throws in turn -- out of the catch block, where nothing is left to
+     * handle it. Whatever the interaction's state, reporting an error must not be able
+     * to become a second, worse one.
+     */
+    private replyWithError;
     private handleMessage;
     private handleReaction;
     private gracefulShutdown;