meocord 4.1.0-beta.6 → 4.1.0-beta.7

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # meocord
 
+## 4.1.0-beta.7
+
+### Minor Changes
+
+- [#257](https://github.com/meocord/meocord/pull/257) [`afa139d`](https://github.com/meocord/meocord/commit/afa139debcc8e4accfe3f5c2a8997dbe9d0fb4d3) Thanks [@l7aromeo](https://github.com/l7aromeo)! - `MeoCordTestingModule.fromApp(App, options?)` builds a testing module from a whole `@MeoCord` app, wired as the bot wires it: its controllers, services, providers and cooldown store, with its stages, translator, presenter, message options, theme and observers. A test no longer lists the app's controllers and providers again. `options.providers` replaces the app's by token, before anything is made, so a database factory the test replaces never runs; `options.controllers` and `options.observers` add a test's own; the `override*()` methods still apply. The app's services are made at `init()`, as the bot makes them before it logs in.
+
+  A class that injects the Discord `Client` in a testing module that was given none is now refused with what to do, `{ provide: Client, useValue: createMockClient() }`, where it read `No bindings found for service: "Client"`.
+
+- [#258](https://github.com/meocord/meocord/pull/258) [`f9189b9`](https://github.com/meocord/meocord/commit/f9189b9b1008a9fee97ede546466b302afe71e92) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A context menu handler is typed with the kind its builder's `setType()` names. With `.setType(ApplicationCommandType.User)`, `@Command('Report user', ReportUserBuilder)` gives the handler a `UserContextMenuCommandInteraction`, and a handler declaring `MessageContextMenuCommandInteraction` no longer compiles. It is caught however the interaction is imported, an `import { type … }` included, where the check as the bot starts needed it imported as a value. Such a handler was broken anyway: dispatch sends a builder's command only to a handler of its kind, so its first click already failed. Declare the kind the builder's `setType()` names.
+
+  Nothing new is needed: MeoCord adds the kind to discord.js's `ContextMenuCommandBuilder.setType` for the compiler alone, and nothing changes at runtime. A builder whose kind the compiler can't tell, one that never calls `setType()` or picks the kind at runtime, gives either kind as before, and is still checked as the bot starts.
+
+### Patch Changes
+
+- [#260](https://github.com/meocord/meocord/pull/260) [`18334ec`](https://github.com/meocord/meocord/commit/18334ecb55c1301586606e4c8d7a9a6ddf4173a1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - The package includes `dist/cli.json`, which describes the `meocord` CLI: every command and subcommand, with its aliases, arguments, options, defaults, choices and descriptions, in the order `meocord --help` lists them. The build writes it from the program the CLI runs, so it always matches the installed version, and a tool can read it as data, without running the CLI. `schemaVersion` changes only when a change to the shape would break a reader.
+
+- [#261](https://github.com/meocord/meocord/pull/261) [`701890b`](https://github.com/meocord/meocord/commit/701890b82e7edad7fa020cc4764f4fd7c5fdfb51) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A message `@Defer` locked is put back when its handler answers only with a follow-up, returns without answering, or throws. On a message with an uploaded file, such as an image in a Components V2 card, a click soon after the message was sent could leave it locked instead: its buttons and selects disabled under the loading view, for good. The lock's edit has Discord process the uploaded file again, and MeoCord, seeing the message change from what its edit returned, took it for someone else's edit and left it alone. It now keeps the time Discord stamps on its own edit, and leaves a message as it is only when it shows a later edit. The file stays attached, and a select that was clicked comes back with its options and defaults as the message had them, not the user's pick.
+
+  `meocord/testing`: a mock interaction's `editReply()` and `fetchReply()` now keep its message as Discord does. Components get their ids, media resolves, a file uploaded with the message comes back loading from the first edit that keeps it, and each edit is stamped with its time. `createMockMessage` takes `editedTimestamp`.
+
+- [#259](https://github.com/meocord/meocord/pull/259) [`01f11d4`](https://github.com/meocord/meocord/commit/01f11d4a0b024ce5a1fd5b83acea5476ae58ca56) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A bot whose commands only one handler or one builder could ever take stops when it is created, as `meocord start`, `meocord register`, a shard manager and a testing module build it, naming both:
+
+  - two handlers of one slash command name or subcommand path, or of one context menu name and kind, where only the first ever ran: `StatsController.stats and AdminController.adminStats both handle the slash command "stats", so only StatsController.stats would ever run.`;
+  - two builder classes that build one application command, where only the first was registered, with a warning: `StatsBuilder on StatsController.stats and CopiedStatsBuilder on StatsController.statistics both build the slash command "stats"…`.
+
+  One builder on a command and its own subcommand paths is still one command, and a user and a message context menu may still share a name. See [Upgrading to 4.1](https://meocord.dev/docs/4.1/migrating#two-handlers-of-one-command-stop-the-bot).
+
+- [#254](https://github.com/meocord/meocord/pull/254) [`2b02b0e`](https://github.com/meocord/meocord/commit/2b02b0ea9e8ad9f8e594ae14e32ba76400ee3275) Thanks [@l7aromeo](https://github.com/l7aromeo)! - A slash command builder given on a subcommand path, such as `@Command('settings notify email', SettingsCommandBuilder)`, is named for what it is. A builder that builds its name from the path fails as before, now with a message naming the handler: `SettingsSlashController.notifyEmail declares the builder SettingsCommandBuilder on "settings notify email", which is a subcommand path: the builder of its command, "settings", describes it`, with what to declare instead, where it said "Invalid string format" and advised checking name lengths. A builder that names its command itself keeps working, and is warned about once as the bot starts, with the same advice: declare the handler with `@Command('settings notify email', CommandType.SLASH)`, and give the builder to `@Command('settings')`.
+
+- [#255](https://github.com/meocord/meocord/pull/255) [`2852892`](https://github.com/meocord/meocord/commit/2852892922694fb883c8244b9469781e152468c1) Thanks [@l7aromeo](https://github.com/l7aromeo)! - An observer is told a message command's usage error as `'invalid'`, the user's input that doesn't fit, as it is told a `ValidationError`. It was told `'error'`, so metrics counted a user's typo as a fault of the bot. This covers a word of the wrong type, a param left out, a flag the command lacks, a command sent where it doesn't work, and a parent's words alone, answered with its subcommands. A dashboard that counts `'error'` sees these under `'invalid'` from this release.
+
 ## 4.1.0-beta.6
 
 ### Minor Changes

package/dist/cjs/_shared/{explained-error-CtgL_q_6.cjs → explained-error-BRrfk1lT.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var node_crypto = require('node:crypto');
-var themeResolvers = require('./theme-resolvers-DhoRhqJV.cjs');
+var themeResolvers = require('./theme-resolvers-B4BV5Ikl.cjs');
 
 /** Whether an IPC message is one of MeoCord's own, rather than one of discord.js's. */ function isShardMessage(message) {
     return typeof message === 'object' && message !== null && 'meocord' in message;

package/dist/cjs/_shared/{providers-BXnrmm9p.cjs → providers-CIA3ykpw.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 require('reflect-metadata');
-var themeResolvers = require('./theme-resolvers-DhoRhqJV.cjs');
+var themeResolvers = require('./theme-resolvers-B4BV5Ikl.cjs');
 var discord_js = require('discord.js');
 var enum_index = require('../enum/index.cjs');
 var node_async_hooks = require('node:async_hooks');
@@ -1025,7 +1025,7 @@ function observersOf(container) {
 /** How a call that threw `error` ended. */ function outcomeOf(error) {
     if (error instanceof themeResolvers.GuardDeniedError) return 'denied';
     if (error instanceof themeResolvers.CooldownError) return 'cooldown';
-    if (error instanceof themeResolvers.ValidationError) return 'invalid';
+    if (error instanceof themeResolvers.ValidationError || error instanceof themeResolvers.MessageUsageError) return 'invalid';
     if (error instanceof themeResolvers.UserError) return 'refused';
     if (error instanceof themeResolvers.CommandNotFoundError) return 'not-found';
     return 'error';

package/dist/cjs/_shared/{shard-context-BmA9OoaF.cjs → shard-context-fX-JKqOi.cjs}

@@ -1,11 +1,15 @@
 'use strict';
 
-var themeResolvers = require('./theme-resolvers-DhoRhqJV.cjs');
-var translateError = require('./translate-error-CNY8ic6A.cjs');
+var themeResolvers = require('./theme-resolvers-B4BV5Ikl.cjs');
+var translateError = require('./translate-error-DtdMVhf7.cjs');
 var discord_js = require('discord.js');
-var providers = require('./providers-BXnrmm9p.cjs');
+var providers = require('./providers-CIA3ykpw.cjs');
 require('reflect-metadata');
 var enum_index = require('../enum/index.cjs');
+var crypto = require('crypto');
+var fs = require('fs');
+var path = require('path');
+var Table = require('cli-table3');
 require('node:crypto');
 
 const NO_GLOBAL_STAGES = {
@@ -613,6 +617,368 @@ function describeCall(context) {
     }
 }
 
+/** Discord's rule for a chat input command or option name, localised or not. */ const CHAT_INPUT_NAME = /^[-_'\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$/u;
+const DISCORD_LOCALES = new Set(Object.values(discord_js.Locale));
+/** The entries of a localization map, or none when it is absent or null. */ const entriesOf$1 = (map)=>typeof map === 'object' && map !== null ? Object.entries(map) : [];
+/**
+ * What Discord would reject in a command's localised names and descriptions, checked before sending
+ * so the error names the field instead of arriving as an opaque 50035. The command's own names and
+ * descriptions are left to discord.js's builders and to Discord.
+ *
+ * @returns One line per problem, such as `"ban" description_localizations.ja: 104 characters (limit 100)`.
+ */ function localizationProblems(commandName, body) {
+    const problems = [];
+    const chatInput = body.type === undefined || body.type === discord_js.ApplicationCommandType.ChatInput;
+    const check = (path, node, rules)=>{
+        for (const [locale, value] of entriesOf$1(node.name_localizations)){
+            const field = `${path}name_localizations.${locale}`;
+            // An unknown locale is the problem to report; lowercasing for it could throw on a malformed tag.
+            if (!DISCORD_LOCALES.has(locale)) {
+                problems.push(`"${commandName}" ${field}: "${locale}" is not a Discord locale`);
+                continue;
+            }
+            if (value === null) continue;
+            if (typeof value !== 'string' || value.length < 1 || value.length > (rules.chatInputName ? 32 : 100)) {
+                problems.push(`"${commandName}" ${field}: ${describeLength(value)} (1 to ${rules.chatInputName ? 32 : 100})`);
+            } else if (rules.chatInputName && (!CHAT_INPUT_NAME.test(value) || value !== value.toLocaleLowerCase(locale))) {
+                problems.push(`"${commandName}" ${field}: "${value}" must be lowercase letters, numbers, - _ or ' with no spaces`);
+            }
+        }
+        if (!rules.descriptions) return;
+        for (const [locale, value] of entriesOf$1(node.description_localizations)){
+            const field = `${path}description_localizations.${locale}`;
+            if (!DISCORD_LOCALES.has(locale)) problems.push(`"${commandName}" ${field}: "${locale}" is not a Discord locale`);
+            if (value === null) continue;
+            if (typeof value !== 'string' || value.length < 1 || value.length > 100) {
+                problems.push(`"${commandName}" ${field}: ${describeLength(value)} (1 to 100)`);
+            }
+        }
+    };
+    // Context menu names allow spaces and capitals, and none of them has a description.
+    const contextMenu = body.type === discord_js.ApplicationCommandType.User || body.type === discord_js.ApplicationCommandType.Message;
+    check('', body, {
+        chatInputName: chatInput,
+        descriptions: !contextMenu
+    });
+    const walk = (path, options)=>{
+        if (!Array.isArray(options)) return;
+        for (const option of options){
+            const at = `${path}${String(option.name)}.`;
+            check(`options.${at}`, option, {
+                chatInputName: true,
+                descriptions: true
+            });
+            if (Array.isArray(option.choices)) {
+                for (const choice of option.choices){
+                    check(`options.${at}choices.${String(choice.name)}.`, choice, {
+                        chatInputName: false,
+                        descriptions: false
+                    });
+                }
+            }
+            walk(at, option.options);
+        }
+    };
+    walk('', body.options);
+    return problems;
+}
+function describeLength(value) {
+    return typeof value === 'string' ? `${value.length} characters` : `not a string`;
+}
+
+/** What Discord assumes a command body is when it carries no type of its own. */ const DEFAULT_APPLICATION_COMMAND_TYPE = discord_js.ApplicationCommandType.ChatInput;
+/** The body a builder registers, which is what Discord sees; throws when the builder is incomplete. */ function serialise(builder) {
+    return typeof builder.toJSON === 'function' ? builder.toJSON() : builder;
+}
+/**
+ * The identity Discord gives a command. The numeric type leads, so the halves never read apart
+ * wrongly; an absent type is the chat input one Discord infers, so untyped slash builders collide.
+ */ function registrationKey(body, fallbackName) {
+    const type = typeof body.type === 'number' ? body.type : DEFAULT_APPLICATION_COMMAND_TYPE;
+    return `${type}:${typeof body.name === 'string' ? body.name : fallbackName}`;
+}
+/**
+ * Every command the controllers declare, read from their prototypes: nothing is constructed.
+ *
+ * @returns The commands, or `undefined` when a builder cannot be serialised. Registration then sends
+ *   nothing, since a bulk update without that command would delete it from Discord.
+ */ function collectCommands(controllerClasses, logger) {
+    // Keyed by type and name: Discord treats that pair as one command, so a user and a message context
+    // menu may share a name, and a command split across methods sends its builder once.
+    const byKey = new Map();
+    const broken = [];
+    const unlocalizable = [];
+    for (const controllerClass of controllerClasses){
+        const commandMap = themeResolvers.getCommandMap(controllerClass.prototype) ?? {};
+        for(const commandName in commandMap){
+            for (const { builder, builderClass, type, guilds } of commandMap[commandName]){
+                if (!(type in enum_index.CommandType) || !builder) continue;
+                let body;
+                try {
+                    body = serialise(builder);
+                } catch (error) {
+                    broken.push(`"${commandName}" (${error instanceof Error ? error.message : String(error)})`);
+                    continue;
+                }
+                const key = registrationKey(body, commandName);
+                const existing = byKey.get(key);
+                if (existing === undefined) {
+                    const name = typeof body.name === 'string' ? body.name : commandName;
+                    unlocalizable.push(...localizationProblems(name, body));
+                    byKey.set(key, {
+                        builderClass: builderClass ?? builder,
+                        command: {
+                            name,
+                            body,
+                            ...guilds && {
+                                guilds
+                            }
+                        }
+                    });
+                } else if (existing.builderClass !== (builderClass ?? builder)) {
+                    // Refused when the app is created; kept for a caller that collects commands on its own, never thrown
+                    logger.warn(`Command "${existing.command.name}" is built more than once for the same application command type; ` + `only the first builder is registered. Two builders of one type cannot both own a name, so declare ` + `the builder on a single @Command and give the others the plain CommandType.`);
+                }
+            }
+        }
+    }
+    if (broken.length > 0) {
+        logger.error(`No commands were registered: ${broken.length} builder(s) could not be serialised: ${broken.join(', ')}. ` + `Registering the rest would remove these from Discord.`);
+        return undefined;
+    }
+    if (unlocalizable.length > 0) {
+        logger.error(`No commands were registered: Discord would reject ${unlocalizable.length} localization(s):\n` + unlocalizable.map((problem)=>`  ${problem}`).join('\n'));
+        return undefined;
+    }
+    return [
+        ...byKey.values()
+    ].map(({ command })=>command);
+}
+const ids = (list)=>[
+        ...new Set((list ?? []).map((id)=>id?.trim()).filter((id)=>!!id))
+    ];
+const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`;
+/** Where every command goes regardless of `guilds`: `--guild`, or `developmentGuild` in development. */ const everythingTarget = ({ config, development, onlyGuild })=>onlyGuild?.trim() || (development ? config?.developmentGuild?.trim() : undefined);
+/**
+ * Whether `commands.guilds` names guilds but no ids, as `[process.env.GUILD_ID]` does with the variable
+ * unset. The default scope is then nowhere: registering globally instead would publish the commands
+ * everywhere.
+ */ function defaultGuildsEmpty(options) {
+    const guilds = options.config?.guilds ?? [];
+    return !everythingTarget(options) && guilds.length > 0 && ids(guilds).length === 0;
+}
+/**
+ * Where each command is sent: one bulk update per scope. A scope's update replaces everything the
+ * application has there, so the default scope is always included, even when it ends up empty.
+ */ function planTargets(commands, options, logger) {
+    const everythingTo = everythingTarget(options);
+    if (everythingTo) return [
+        {
+            scope: {
+                guild: everythingTo
+            },
+            commands
+        }
+    ];
+    const defaultGuilds = ids(options.config?.guilds);
+    const nowhere = defaultGuildsEmpty(options);
+    const targets = new Map();
+    const add = (scope, command)=>{
+        const key = scopeKey(scope);
+        if (!targets.has(key)) targets.set(key, {
+            scope,
+            commands: []
+        });
+        if (command) targets.get(key).commands.push(command);
+    };
+    if (defaultGuilds.length === 0 && !nowhere) add('global');
+    for (const guild of defaultGuilds)add({
+        guild
+    });
+    const unregistered = [];
+    for (const command of commands){
+        if (command.guilds) {
+            const own = ids(command.guilds);
+            // Falling back to the default scope could publish a staff-only command everywhere.
+            if (own.length === 0) logger.warn(`Command "${command.name}" lists no guild ids in its builder, so it is not registered.`);
+            for (const guild of own)add({
+                guild
+            }, command);
+        } else if (nowhere) {
+            unregistered.push(`"${command.name}"`);
+        } else if (defaultGuilds.length === 0) {
+            add('global', command);
+        } else {
+            for (const guild of defaultGuilds)add({
+                guild
+            }, command);
+        }
+    }
+    if (nowhere) {
+        const outcome = unregistered.length === 0 ? 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
+        logger.warn(`commands.guilds lists no guild id, as an unset environment variable leaves it, so ${outcome}. ` + `Set the guild ids, or remove commands.guilds to register globally.`);
+    }
+    return [
+        ...targets.values()
+    ];
+}
+/** The scopes this configuration names that registration is not sending to, where leftovers can sit. */ function otherScopes(commands, targets, config) {
+    const sent = new Set(targets.map(({ scope })=>scopeKey(scope)));
+    const named = [
+        'global',
+        ...ids([
+            ...config?.guilds ?? [],
+            config?.developmentGuild,
+            ...commands.flatMap((command)=>command.guilds ?? [])
+        ]).map((guild)=>({
+                guild
+            }))
+    ];
+    return named.filter((scope)=>!sent.has(scopeKey(scope)));
+}
+const routeFor = (applicationId, scope)=>scope === 'global' ? discord_js.Routes.applicationCommands(applicationId) : discord_js.Routes.applicationGuildCommands(applicationId, scope.guild);
+const describeScope = (scope)=>scope === 'global' ? 'globally' : `to guild ${scope.guild}`;
+/** The development cache of what was last sent, per application and scope. Undefined without node_modules. */ function cacheFile(applicationId, scope) {
+    const nodeModules = path.resolve(process.cwd(), 'node_modules');
+    if (!fs.existsSync(nodeModules)) return undefined;
+    return path.join(nodeModules, '.cache', 'meocord', `commands-${applicationId}-${scopeKey(scope)}.json`);
+}
+const hashOf = (commands)=>crypto.createHash('sha256').update(JSON.stringify(commands.map(({ body })=>body))).digest('hex');
+function readHash(file, logger) {
+    if (!file || !fs.existsSync(file)) return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8')).hash;
+    } catch (error) {
+        logger.debug(`Could not read the registered commands, so they are sent again: ${String(error)}`);
+        return undefined;
+    }
+}
+function writeHash(file, hash, logger) {
+    if (!file) return;
+    try {
+        fs.mkdirSync(path.dirname(file), {
+            recursive: true
+        });
+        fs.writeFileSync(file, `${JSON.stringify({
+            hash
+        })}\n`);
+    } catch (error) {
+        logger.debug(`Could not record the registered commands: ${String(error)}`);
+    }
+}
+function logRegistered(target, logger) {
+    const table = new Table({
+        head: [
+            'Name',
+            'Type',
+            'Sub-commands'
+        ],
+        colWidths: [
+            null,
+            null,
+            30
+        ],
+        wordWrap: true
+    });
+    const typeNames = {
+        1: 'SlashCommand',
+        2: 'UserContextMenu',
+        3: 'MessageContextMenu',
+        4: 'PrimaryEntryPoint'
+    };
+    for (const { name, body } of target.commands){
+        const options = Array.isArray(body.options) ? body.options : [];
+        table.push([
+            name,
+            typeNames[typeof body.type === 'number' ? body.type : 1] ?? 'Command',
+            options.map((option)=>option.name).join(', ')
+        ]);
+    }
+    logger.log(`Registered ${target.commands.length} bot commands ${describeScope(target.scope)}:\n${table.toString()}`);
+}
+/**
+ * Registers the application's commands with Discord: one bulk update per scope.
+ *
+ * Production always sends: a bulk update is idempotent, so comparing with what Discord holds first
+ * would only add a request. In development (`development: true`) a scope whose payload matches the
+ * last one sent from this project is skipped, unless `force` is set. Afterwards, the scopes the
+ * configuration names but did not send to are checked for leftovers, which `clearOther` removes, except
+ * in a development run sending to `developmentGuild`, which only warns.
+ * Failures are logged, never thrown.
+ *
+ * @returns Whether every scope was registered or skipped as unchanged.
+ */ async function registerCommands(options) {
+    const { rest, applicationId, controllerClasses, logger, config, development, onlyGuild, force = false } = options;
+    const commands = collectCommands(controllerClasses, logger);
+    if (!commands) return false;
+    const targets = planTargets(commands, {
+        config,
+        development,
+        onlyGuild
+    }, logger);
+    // Commands the configuration meant for guilds went nowhere, and what it would clear cannot be trusted
+    const guildsEmpty = defaultGuildsEmpty({
+        config,
+        development,
+        onlyGuild
+    });
+    let succeeded = !guildsEmpty;
+    let sent = false;
+    for (const target of targets){
+        const file = development ? cacheFile(applicationId, target.scope) : undefined;
+        const hash = hashOf(target.commands);
+        if (development && !force && readHash(file, logger) === hash) {
+            logger.log(`Commands ${describeScope(target.scope)} are unchanged; not registering them again.`);
+            continue;
+        }
+        try {
+            await rest.put(routeFor(applicationId, target.scope), {
+                body: target.commands.map(({ body })=>body)
+            });
+            sent = true;
+            if (development) writeHash(file, hash, logger);
+            logRegistered(target, logger);
+        } catch (error) {
+            succeeded = false;
+            logger.error(`Error registering commands ${describeScope(target.scope)}:`, error);
+        }
+    }
+    // Development and production often share one application, so a development guild run never clears.
+    const toDevelopmentGuild = development && !!config?.developmentGuild?.trim();
+    const keptBecause = toDevelopmentGuild ? 'while commands go to the development guild, since a production bot sharing this application may own them' : guildsEmpty ? 'while commands.guilds lists no guild id' : undefined;
+    if (sent && !onlyGuild) await reportOtherScopes(options, commands, targets, keptBecause);
+    return succeeded;
+}
+/**
+ * Warns about, or with `clearOther` removes, this application's commands left in scopes not sent to.
+ * Given `keptBecause`, as for a development guild run, it only warns, saying why.
+ */ async function reportOtherScopes({ rest, applicationId, config, logger }, commands, targets, keptBecause) {
+    for (const scope of otherScopes(commands, targets, config)){
+        let existing;
+        try {
+            existing = await rest.get(routeFor(applicationId, scope));
+        } catch (error) {
+            // A guild the bot is not in answers 50001; there is nothing of ours to find there.
+            logger.debug(`Could not list the commands registered ${describeScope(scope)}: ${String(error)}`);
+            continue;
+        }
+        if (!Array.isArray(existing) || existing.length === 0) continue;
+        const names = existing.map(({ name })=>name).join(', ');
+        if (!config?.clearOther || keptBecause) {
+            logger.warn(`${existing.length} command(s) are still registered ${describeScope(scope)} (${names}), which this ` + `configuration does not register to, so Discord keeps showing them there. ` + (config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : 'Set commands.clearOther to remove them.'));
+            continue;
+        }
+        try {
+            await rest.put(routeFor(applicationId, scope), {
+                body: []
+            });
+            logger.log(`Removed ${existing.length} command(s) left registered ${describeScope(scope)}: ${names}`);
+        } catch (error) {
+            logger.error(`Error removing the commands left registered ${describeScope(scope)}:`, error);
+        }
+    }
+}
+
 /**
  * Every customId-pattern route of the given controllers, most specific first, read from metadata alone.
  * Throws for two handlers whose patterns match the same customIds of one component type; one handler
@@ -2271,7 +2637,7 @@ const COMMAND_TYPES = new Set([
         return undefined;
     }
 }
-/** The description of the command or subcommand at `path` within a command's JSON. */ function describe$1(json, path) {
+/** The description of the command or subcommand at `path` within a command's JSON. */ function describe$2(json, path) {
     let node = json;
     for (const segment of path.split(' ').slice(1)){
         node = node?.options?.find((option)=>option.name === segment);
@@ -2412,7 +2778,7 @@ const COMMAND_TYPES = new Set([
                 for (const { methodName, type, builder } of metas){
                     if (COMMAND_TYPES.has(type)) {
                         const command = builderJson(builder) ?? commandJson.get(name.split(' ')[0]);
-                        const description = describe$1(command, name);
+                        const description = describe$2(command, name);
                         entries.push({
                             ...base(methodName),
                             kind: 'command',
@@ -2484,6 +2850,74 @@ const COMMAND_TYPES = new Set([
     }
 }
 
+const where = ({ controllerClass, meta })=>`${controllerClass.name}.${meta.methodName}`;
+/** The context menu kind a handler's builder registers; `undefined` for one without a builder, which takes both. */ const contextMenuKind = (meta)=>meta.builder?.type;
+/** A command as an error names it: `slash command "settings notify"`, `user context menu command "Report"`. */ function describe$1(type, name, kind) {
+    if (type !== enum_index.CommandType.CONTEXT_MENU) return `slash command "${name}"`;
+    const label = kind === discord_js.ApplicationCommandType.User ? 'user ' : kind === discord_js.ApplicationCommandType.Message ? 'message ' : '';
+    return `${label}context menu command "${name}"`;
+}
+/** Whether two handlers declared under one name would both be sent the same interactions. */ function overlap(a, b) {
+    if (a.type !== enum_index.CommandType.CONTEXT_MENU) return true;
+    const [kindA, kindB] = [
+        contextMenuKind(a),
+        contextMenuKind(b)
+    ];
+    return kindA === undefined || kindB === undefined || kindA === kindB;
+}
+/**
+ * Refuses the commands of which only one could ever run or be registered: two handlers of one slash command
+ * name or subcommand path, or of one context menu name and kind, and two builder classes that build one
+ * application command. One builder on a command and its own subcommand paths builds one command, and a user and a
+ * message context menu may share a name. The app's start, `meocord register`, the shard manager and the testing
+ * module call it before anything registers or runs.
+ *
+ * @throws Error naming both handlers, and both builders when two build one command, with what to do instead.
+ */ function assertDistinctCommands(controllerClasses) {
+    const handlers = new Map();
+    const builders = new Map();
+    // A controller listed twice is one controller
+    for (const controllerClass of new Set(controllerClasses)){
+        const commandMap = themeResolvers.getCommandMap(controllerClass.prototype) ?? {};
+        for (const [name, metas] of Object.entries(commandMap)){
+            for (const meta of metas){
+                // Components route on a pattern, which the component routes check
+                if (themeResolvers.isCustomIdRouted(meta.type)) continue;
+                const here = {
+                    controllerClass,
+                    meta
+                };
+                const key = `${meta.type}\0${name}`;
+                const earlier = (handlers.get(key) ?? []).find((other)=>overlap(other.meta, meta));
+                if (earlier) {
+                    throw new Error(`${where(earlier)} and ${where(here)} both handle the ${describe$1(meta.type, name, contextMenuKind(meta) ?? contextMenuKind(earlier.meta))}, ` + `so only ${where(earlier)} would ever run. Keep one handler for it, or give the other a name or ` + `subcommand path of its own.`);
+                }
+                handlers.set(key, [
+                    ...handlers.get(key) ?? [],
+                    here
+                ]);
+                if (!meta.builder || !meta.builderClass) continue;
+                let body;
+                try {
+                    body = serialise(meta.builder);
+                } catch  {
+                    continue;
+                }
+                const registered = registrationKey(body, name);
+                const built = builders.get(registered);
+                if (!built) {
+                    builders.set(registered, {
+                        ...here,
+                        name: typeof body.name === 'string' ? body.name : name
+                    });
+                } else if (built.meta.builderClass !== meta.builderClass) {
+                    throw new Error(`${built.meta.builderClass.name} on ${where(built)} and ${meta.builderClass.name} on ${where(here)} both ` + `build the ${describe$1(meta.type, built.name, contextMenuKind(meta))}, and Discord registers one command ` + `per name and type, so only the first would be. Keep one builder, on a single @Command, and declare ` + `the other handlers with CommandType.${meta.type}.`);
+                }
+            }
+        }
+    }
+}
+
 /** Where each shard's client keeps the function that runs a `ShardContext.call` in that shard. */ const SHARD_CALL_KEY = Symbol.for('meocord.shardCall');
 /** How long `ShardContext.call` waits for a shard to answer. */ const SHARD_CALL_TIMEOUT_MS = 10000;
 /**
@@ -2661,6 +3095,7 @@ exports.SHARD_CALL_KEY = SHARD_CALL_KEY;
 exports.ShardContext = ShardContext;
 exports.appPresenterOf = appPresenterOf;
 exports.appStages = appStages;
+exports.assertDistinctCommands = assertDistinctCommands;
 exports.bindAppPresenter = bindAppPresenter;
 exports.bindGlobalStages = bindGlobalStages;
 exports.buildComponentRoutes = buildComponentRoutes;
@@ -2677,6 +3112,7 @@ exports.matchMessageRoute = matchMessageRoute;
 exports.messageParamsFor = messageParamsFor;
 exports.ownInteractionListener = ownInteractionListener;
 exports.prepareHandlerStages = prepareHandlerStages;
+exports.registerCommands = registerCommands;
 exports.replyWithUserError = replyWithUserError;
 exports.runHandler = runHandler;
 exports.runReadyHooks = runReadyHooks;