meocord 4.2.0 → 4.2.1

package/dist/esm/core/command-registration.js

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'fs';
 import path from 'path';
 import { ApplicationCommandType, Routes } from 'discord.js';
 import CliTable3 from 'cli-table3';
@@ -103,19 +103,35 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     const guilds = options.config?.guilds ?? [];
     return !everythingTarget(options) && guilds.length > 0 && ids(guilds).length === 0;
 }
+/** Whether a command is an activity's primary entry point, which Discord takes only globally. */ const isEntryPoint = (command)=>command.body.type === ApplicationCommandType.PrimaryEntryPoint;
+/** What a blank guild to register every command to says, as an unset variable gives one. */ const BLANK_GUILD = 'No commands were registered: the guild to register to is blank. Give a guild id, or leave it out to register where commands.* says.';
 /**
  * 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 included even when it ends up empty, unless `commands.guilds` lists no guild id.
+ *
+ * A primary entry point command goes in the global update, as Discord refuses a guild update that holds one. A run
+ * that sends everything to one guild sends nothing global, so it leaves the entry point out.
  */ function planTargets(commands, options, logger) {
+    // Registering to the default scopes instead could publish everywhere
+    if (options.onlyGuild !== undefined && !options.onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return [];
+    }
     const everythingTo = everythingTarget(options);
-    if (everythingTo) return [
-        {
-            scope: {
-                guild: everythingTo
-            },
-            commands
+    if (everythingTo) {
+        // A global update from here would hold only what this run sends, deleting the application's other global commands
+        for (const command of commands.filter(isEntryPoint)){
+            logger.warn(`Entry point command "${command.name}" is registered globally only; a production run or \`meocord register\` registers it.`);
         }
-    ];
+        return [
+            {
+                scope: {
+                    guild: everythingTo
+                },
+                commands: commands.filter((command)=>!isEntryPoint(command))
+            }
+        ];
+    }
     const defaultGuilds = ids(options.config?.guilds);
     const nowhere = defaultGuildsEmpty(options);
     const targets = new Map();
@@ -133,7 +149,12 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     });
     const unregistered = [];
     for (const command of commands){
-        if (command.guilds) {
+        if (isEntryPoint(command)) {
+            if (command.guilds) {
+                logger.warn(`Entry point command "${command.name}" can only be registered globally, so the guilds its builder lists are ignored.`);
+            }
+            add('global', command);
+        } else 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.`);
@@ -151,7 +172,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
         }
     }
     if (nowhere) {
-        const outcome = unregistered.length === 0 ? 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
+        const outcome = unregistered.length === 0 ? targets.has('global') ? 'only the entry point command is registered globally' : '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 [
@@ -180,28 +201,57 @@ const describeScope = (scope)=>scope === 'global' ? 'globally' : `to guild ${sco
     return path.join(nodeModules, '.cache', 'meocord', `commands-${applicationId}-${scopeKey(scope)}.json`);
 }
 const hashOf = (commands)=>createHash('sha256').update(JSON.stringify(commands.map(({ body })=>body))).digest('hex');
-function readHash(file, logger) {
+function readRecord(file, logger) {
     if (!file || !existsSync(file)) return undefined;
     try {
-        return JSON.parse(readFileSync(file, 'utf8')).hash;
+        return JSON.parse(readFileSync(file, 'utf8'));
     } catch (error) {
         logger.debug(`Could not read the registered commands, so they are sent again: ${String(error)}`);
         return undefined;
     }
 }
-function writeHash(file, hash, logger) {
+function writeRecord(file, record, logger) {
     if (!file) return;
     try {
         mkdirSync(path.dirname(file), {
             recursive: true
         });
-        writeFileSync(file, `${JSON.stringify({
-            hash
-        })}\n`);
+        writeFileSync(file, `${JSON.stringify(record)}\n`);
     } catch (error) {
         logger.debug(`Could not record the registered commands: ${String(error)}`);
     }
 }
+/** Forgets what development last sent to a scope, once that scope is written some other way. */ function forgetRecord(file, logger) {
+    if (!file || !existsSync(file)) return;
+    try {
+        rmSync(file);
+    } catch (error) {
+        logger.debug(`Could not forget the registered commands: ${String(error)}`);
+    }
+}
+/**
+ * Each command's `id:version`, sorted, from what Discord lists or answers a bulk update with; `undefined` for anything
+ * else. Discord gives a command a new version whenever it is updated, so the set changes with any edit, removal or
+ * re-registration, from this checkout or any other.
+ */ function versionsOf(commands) {
+    if (!Array.isArray(commands)) return undefined;
+    const versions = commands.map((command)=>{
+        const { id, version } = command ?? {};
+        return typeof id === 'string' && typeof version === 'string' ? `${id}:${version}` : undefined;
+    });
+    return versions.every((version)=>version !== undefined) ? versions.sort() : undefined;
+}
+/** Whether Discord still holds a scope as development last sent it, by each command's version; a failed listing doesn't. */ async function stillAsSent(rest, route, record, scope, logger) {
+    if (!record.versions) return false;
+    let registered;
+    try {
+        registered = await rest.get(route);
+    } catch (error) {
+        logger.debug(`Could not list the commands registered ${describeScope(scope)}, so they are sent again: ${String(error)}`);
+        return false;
+    }
+    return versionsOf(registered)?.join('\n') === record.versions.join('\n');
+}
 function logRegistered(target, logger) {
     const table = new CliTable3({
         head: [
@@ -224,22 +274,29 @@ function logRegistered(target, logger) {
     };
     for (const { name, body } of target.commands){
         const options = Array.isArray(body.options) ? body.options : [];
+        // A subcommand or a subcommand group, not a plain option
+        const subcommands = options.filter((option)=>option.type === 1 || option.type === 2);
         table.push([
             name,
             typeNames[typeof body.type === 'number' ? body.type : 1] ?? 'Command',
-            options.map((option)=>option.name).join(', ')
+            subcommands.map((option)=>option.name).join(', ')
         ]);
     }
     logger.log(`Registered ${target.commands.length} bot commands ${describeScope(target.scope)}:\n${table.toString()}`);
 }
 /**
- * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send, unless
- * `force`. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
+ * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send and still
+ * registered as sent, which one listing per skipped scope checks by each command's version, unless `force`. A blank `onlyGuild` registers nothing. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
  * leftovers, which `clearOther` removes; a development-guild run or a `commands.guilds` with no id only warns. Never
  * throws.
  * @returns Whether every scope was sent or unchanged, and `commands.guilds`, if set, lists a guild id.
  */ async function registerCommands(options) {
     const { rest, applicationId, controllerClasses, logger, config, development, onlyGuild, force = false } = options;
+    // An unset variable passed as the guild; registering to the default scopes instead could publish everywhere
+    if (onlyGuild !== undefined && !onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return false;
+    }
     const commands = collectCommands(controllerClasses, logger);
     if (!commands) return false;
     const targets = planTargets(commands, {
@@ -256,18 +313,26 @@ function logRegistered(target, logger) {
     let succeeded = !guildsEmpty;
     let sent = false;
     for (const target of targets){
-        const file = development ? cacheFile(applicationId, target.scope) : undefined;
+        const file = cacheFile(applicationId, target.scope);
         const hash = hashOf(target.commands);
-        if (development && !force && readHash(file, logger) === hash) {
+        const route = routeFor(applicationId, target.scope);
+        // Unchanged since development last sent it, and still what Discord holds there
+        const record = development && !force ? readRecord(file, logger) : undefined;
+        if (record?.hash === hash && await stillAsSent(rest, route, record, target.scope, logger)) {
             logger.log(`Commands ${describeScope(target.scope)} are unchanged; not registering them again.`);
             continue;
         }
         try {
-            await rest.put(routeFor(applicationId, target.scope), {
+            const answered = await rest.put(route, {
                 body: target.commands.map(({ body })=>body)
             });
             sent = true;
-            if (development) writeHash(file, hash, logger);
+            // Outside development the record would be stale, so the next development start sends again
+            if (development) writeRecord(file, {
+                hash,
+                versions: versionsOf(answered)
+            }, logger);
+            else forgetRecord(file, logger);
             logRegistered(target, logger);
         } catch (error) {
             succeeded = false;
@@ -296,13 +361,17 @@ function logRegistered(target, logger) {
         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.'));
+            // Advising clearOther when it would not apply sends the reader to a setting that changes nothing
+            const advice = !keptBecause ? 'Set commands.clearOther to remove them.' : config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : `They are not removed ${keptBecause}, even with commands.clearOther.`;
+            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. ${advice}`);
             continue;
         }
         try {
             await rest.put(routeFor(applicationId, scope), {
                 body: []
             });
+            // What development last sent there is gone, so its next start sends again
+            forgetRecord(cacheFile(applicationId, scope), logger);
             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);

package/dist/esm/core/command-routes.js

@@ -1,4 +1,4 @@
-import { getCommandMap } from '../decorator/controller.decorator.js';
+import { commandsNamed, getCommandMap } from '../decorator/controller.decorator.js';
 import { resolveCommandPaths, matchesHandler } from '../util/interaction.util.js';
 
 /** The keys a command is routed by, most specific first: a chat command's full path, then its name; none for anything else. */ function commandRouteKeys(interaction) {
@@ -15,7 +15,7 @@ import { resolveCommandPaths, matchesHandler } from '../util/interaction.util.js
  */ function matchCommandRoute(controllers, interaction) {
     for (const key of commandRouteKeys(interaction)){
         for (const controllerClass of controllers){
-            const meta = getCommandMap(controllerClass.prototype)?.[key]?.find((each)=>matchesHandler(each, interaction));
+            const meta = commandsNamed(getCommandMap(controllerClass.prototype), key).find((each)=>matchesHandler(each, interaction));
             if (meta) return {
                 controllerClass,
                 meta

package/dist/esm/core/cooldown-runner.js

@@ -222,19 +222,37 @@ const logger = new Logger('Cooldown');
         const value = by ? await by(context, params) : undefined;
         // Encoded, so a value holding a colon cannot count under another value's key. Without a value, `:by` alone keeps
         // the call apart from a cooldown with no `by` over the same window.
-        const suffix = !by ? '' : value === undefined ? ':by' : `:by:${encodeURIComponent(String(value))}`;
+        const suffix = !by ? '' : value === undefined ? ':by' : `:by:${encodeKeyPart(String(value))}`;
+        const scope = scopeId(per, first);
+        // The caller, for a notice of a refusal under a scope that counts more than one caller
+        const user = scope.startsWith('user:') ? undefined : caller(first).user;
         counted.push({
-            key: `${controller.name}.${methodName}#${id}:${per}:${scopeId(per, first)}${suffix}`,
+            key: `${controller.name}.${methodName}#${id}:${per}:${scope}${suffix}`,
             windowMs,
             uses,
-            per
+            per,
+            user
         });
     }
     return counted;
 }
+// A surrogate with no partner beside it, which encodeURIComponent refuses
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 /**
- * The store key and window of the cooldown each refusal came from, and when its wait ends by the store's clock if
- * the store said, for {@link claimCooldownNotice}.
+ * A value as part of a store key: each well-formed run as `encodeURIComponent` writes it, and each lone surrogate as `%u`
+ * and its four hex digits, which no other value encodes to, since `encodeURIComponent` writes `%` only before two.
+ */ function encodeKeyPart(value) {
+    let encoded = '';
+    let from = 0;
+    for (const { 0: surrogate, index } of value.matchAll(LONE_SURROGATE)){
+        encoded += `${encodeURIComponent(value.slice(from, index))}%u${surrogate.charCodeAt(0).toString(16).toUpperCase()}`;
+        from = index + 1;
+    }
+    return encoded + encodeURIComponent(value.slice(from));
+}
+/**
+ * The store key and window of the cooldown each refusal came from, when its wait ends by the store's clock if the
+ * store said, and the refused caller when the key counts more than one, for {@link claimCooldownNotice}.
  */ const refusalKeys = new WeakMap();
 /** Asks the store about the call under the app's policy, and throws what the answer means for it. */ async function ask(container, counted, peek, call) {
     const store = cooldownStoreOf(container);
@@ -267,7 +285,8 @@ const logger = new Logger('Cooldown');
     refusalKeys.set(refusal, {
         key: blocking.key,
         windowMs: blocking.windowMs,
-        endsAt: verdict.retryTimestamp
+        endsAt: verdict.retryTimestamp,
+        user: blocking.user
     });
     throw refusal;
 }
@@ -290,16 +309,18 @@ const logger = new Logger('Cooldown');
     // retry landing a moment late is refused on the earlier, which its wait holds, before taking the later, which a wait
     // ending then needs for its own notice.
     const bucket = Math.floor(refusal.retryAt.getTime() / NOTICE_BUCKET_MS);
+    // A key counting a server, a channel or everyone is shared by every caller it refuses, each told once
+    const key = refused.user === undefined ? refused.key : `${refused.key}:user:${refused.user}`;
     const notices = refused.endsAt !== undefined ? [
         {
-            key: `${refused.key}:notice:at:${refused.endsAt}`,
+            key: `${key}:notice:at:${refused.endsAt}`,
             limit
         }
     ] : [
         bucket - 1,
         bucket
     ].map((at)=>({
-            key: `${refused.key}:notice:${at}`,
+            key: `${key}:notice:${at}`,
             limit
         }));
     try {

package/dist/esm/core/fallback.js

@@ -7,7 +7,7 @@ import { themeForInteraction, useTheme } from './theme-scope.js';
 import { errorText } from '../common/translate-error.js';
 import { interactionLocale, translatorOfClient, messageLocale, renderText } from '../common/meocord-text.js';
 import { logFailedSend } from '../common/response/send-failure.js';
-import { presenterFor, withSendableFiles, DEFAULT_ATTACHMENT_SIZE_LIMIT, attachmentsOf, renderEmbed, withoutFiles, isTooLarge, REFUSED_AS_TOO_LARGE } from '../common/response/presenter.js';
+import { presenterFor, fitText, TEXT_LIMITS, withSendableFiles, DEFAULT_ATTACHMENT_SIZE_LIMIT, attachmentsOf, renderEmbed, withoutFiles, isTooLarge, REFUSED_AS_TOO_LARGE } from '../common/response/presenter.js';
 import { escapeForLog, quoteForLog } from '../util/user-text.util.js';
 
 const UNKNOWN_INTERACTION = 10062;
@@ -79,7 +79,10 @@ function errorCode(error) {
         return send(reply.withoutFiles);
     }
 }
-/** The text of a reply to a message, after the call's `emojis.warning` when `withEmoji`. */ const replyText = (text, withEmoji)=>withEmoji ? `${useTheme().emojis.warning} ${text}` : text;
+/** The text of a reply to a message, after the call's `emojis.warning` when `withEmoji`, cut to fit a message's content. */ function replyText(text, withEmoji) {
+    const emoji = withEmoji ? `${useTheme().emojis.warning} ` : '';
+    return emoji + fitText(text, TEXT_LIMITS.content - emoji.length);
+}
 /**
  * `text`, answering `error` for `message`: plain, after the call's `emojis.warning` when `withEmoji`, unless the
  * presenter's `messageError` draws it as an embed, coloured as an interaction's view is, with that emoji when it has
@@ -87,28 +90,33 @@ function errorCode(error) {
  * the failure comes back with it, for the caller to report once sent.
  */ async function presentedReply(message, error, text, withEmoji, logger) {
     const presenter = presenterFor(message.client);
+    const translator = translatorOfClient(message.client);
+    const locale = messageLocale(message) ?? translator?.defaultLocale ?? 'en-US';
+    // An empty or whitespace-only message, which Discord refuses, reads as MeoCord's generic error text, so neither the plain reply nor a presenter is left without one
+    const shown = text.trim() === '' ? renderText(translator, locale, {
+        key: 'meocord.fallback.error'
+    }) : text;
     const plain = {
         body: {
-            content: replyText(text, withEmoji)
+            content: replyText(shown, withEmoji)
         }
     };
     const { messageError } = presenter;
     if (!messageError) return plain;
     try {
         const theme = await themeForInteraction(message);
-        const translator = translatorOfClient(message.client);
-        const locale = messageLocale(message) ?? translator?.defaultLocale ?? 'en-US';
         const tone = isUserOutcome(error, message) ? 'warning' : 'danger';
+        const presented = {
+            message: fitText(shown, TEXT_LIMITS.embed),
+            error,
+            tone
+        };
         const drawn = await messageError.call(presenter, {
             message,
             locale,
             mode: 'embed',
             theme
-        }, {
-            message: text,
-            error,
-            tone
-        });
+        }, presented);
         let view = drawn.color === undefined ? {
             ...drawn,
             color: theme.colors.primary
@@ -165,7 +173,8 @@ async function replyToMessage(message, error, logger, withEmoji, answering) {
         await sendReply(reply, (body)=>message.reply({
                 ...body,
                 allowedMentions: {
-                    repliedUser: false
+                    repliedUser: false,
+                    parse: []
                 }
             }));
     } catch (replyError) {

package/dist/esm/core/guard-runner.js

@@ -338,14 +338,27 @@ const wrapperCount = perHandler((prototype, methodName)=>{
     else marks.delete(methodName);
     return true;
 }
+/** The container that made each instance, so a direct call runs in its own app or testing module. */ const instanceContainers = new WeakMap();
+/**
+ * Records each instance `container` makes of `classes` as its own. Two testing modules made from one class each run a
+ * direct call on their own instance in themselves, where the class's metadata names only the last.
+ */ function recordInstanceContainers(container, classes) {
+    for (const cls of classes){
+        container.onActivation(cls, (_context, instance)=>{
+            if (typeof instance === 'object' && instance !== null) instanceContainers.set(instance, container);
+            return instance;
+        });
+    }
+}
 /**
  * Runs a direct call to a guarded handler: the handler's guards, as dispatch resolves them, then the
  * call with a pass for each wrapper inside the one entered, so no guard runs twice.
  */ async function runDirectCall(instance, methodName, args, call) {
     const prototype = Object.getPrototypeOf(instance);
     const controller = instance.constructor;
-    // The app that made the class, or a class it extends: a subclass the app's code makes runs as its base does
-    const container = Reflect.getMetadata(META.container, controller);
+    // The container that made the instance, or else the app that made the class or a class it extends: a subclass the
+    // app's code makes runs as its base does
+    const container = instanceContainers.get(instance) ?? Reflect.getMetadata(META.container, controller);
     if (!container) {
         throw new Error(`${controller.name}.${methodName}: @UseGuard runs its guards through the app that made ${controller.name}, and this ` + `instance was made outside one. Inject ${controller.name}, or call it on an instance the app made.`);
     }
@@ -384,4 +397,4 @@ const wrapperCount = perHandler((prototype, methodName)=>{
     }
 }
 
-export { callGuardedHandler, classChain, classLevelGuards, consumeDispatchMark, declaringPrototype, handlerGuards, handlerMethods, injectedTokens, isGuardWithParams, perHandler, runDirectCall, runGuards, singletonContextError, sourcePrototype, stageClasses, undecoratedConstructor, untypedParameter };
+export { callGuardedHandler, classChain, classLevelGuards, consumeDispatchMark, declaringPrototype, handlerGuards, handlerMethods, injectedTokens, isGuardWithParams, perHandler, recordInstanceContainers, runDirectCall, runGuards, singletonContextError, sourcePrototype, stageClasses, undecoratedConstructor, untypedParameter };

package/dist/esm/core/handler-input.js

@@ -2,6 +2,7 @@ import { ModalSubmitInteraction, ComponentType, StringSelectMenuInteraction, Use
 import { getCommandMap } from '../decorator/controller.decorator.js';
 import { matchComponentRoute } from './component-routes.js';
 import { hasCustomId, isCustomIdRouted, matchesHandler, resolveOptionParams, matchesCommandType } from '../util/interaction.util.js';
+import { setOwn } from '../util/value.util.js';
 import { commandRouteKeys, matchCommandRoute } from './command-routes.js';
 
 /** The entries of a discord.js Collection, or none for anything else, such as a test double's stub. */ const entriesOf = (collection)=>collection instanceof Map ? [
@@ -18,8 +19,8 @@ import { commandRouteKeys, matchCommandRoute } from './command-routes.js';
     for (const [customId, field] of fields){
         const data = field;
         // An upload's `values` are the attachments' ids; discord.js resolves the attachments themselves alongside
-        if (data.type === ComponentType.FileUpload) values[customId] = entriesOf(interaction.fields.getUploadedFiles(customId));
-        else values[customId] = 'value' in data ? data.value : data.values;
+        if (data.type === ComponentType.FileUpload) setOwn(values, customId, entriesOf(interaction.fields.getUploadedFiles(customId)));
+        else setOwn(values, customId, 'value' in data ? data.value : data.values);
     }
     return values;
 }
@@ -78,7 +79,7 @@ import { commandRouteKeys, matchCommandRoute } from './command-routes.js';
         collisions: []
     };
     const fields = interaction instanceof ModalSubmitInteraction ? modalFields(interaction) : selectChoices(interaction);
-    const collisions = Object.keys(routeParams).filter((name)=>name in fields);
+    const collisions = Object.keys(routeParams).filter((name)=>Object.hasOwn(fields, name));
     return {
         params: {
             ...fields,