meocord 4.2.0 → 4.2.1

package/dist/cjs/_shared/{providers-ChvMqnLd.cjs → providers-BZgJyfZS.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
+var controller_decorator = require('./controller.decorator-XKMlcUZz.cjs');
 require('reflect-metadata');
 var node_async_hooks = require('node:async_hooks');
 var inversify = require('inversify');
@@ -505,14 +505,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(controller_decorator.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(controller_decorator.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.`);
     }
@@ -767,19 +780,37 @@ const logger$3 = new controller_decorator.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);
@@ -812,7 +843,8 @@ const logger$3 = new controller_decorator.Logger('Cooldown');
     refusalKeys.set(refusal, {
         key: blocking.key,
         windowMs: blocking.windowMs,
-        endsAt: verdict.retryTimestamp
+        endsAt: verdict.retryTimestamp,
+        user: blocking.user
     });
     throw refusal;
 }
@@ -835,16 +867,18 @@ const logger$3 = new controller_decorator.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 {
@@ -1066,19 +1100,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 === discord_js.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();
@@ -1096,7 +1146,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.`);
@@ -1114,7 +1169,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 [
@@ -1143,28 +1198,57 @@ const describeScope = (scope)=>scope === 'global' ? 'globally' : `to guild ${sco
     return path__default.default.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) {
+function readRecord(file, logger) {
     if (!file || !fs.existsSync(file)) return undefined;
     try {
-        return JSON.parse(fs.readFileSync(file, 'utf8')).hash;
+        return JSON.parse(fs.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 {
         fs.mkdirSync(path__default.default.dirname(file), {
             recursive: true
         });
-        fs.writeFileSync(file, `${JSON.stringify({
-            hash
-        })}\n`);
+        fs.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 || !fs.existsSync(file)) return;
+    try {
+        fs.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 Table__default.default({
         head: [
@@ -1187,22 +1271,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, {
@@ -1219,18 +1310,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;
@@ -1259,13 +1358,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);
@@ -4854,15 +4957,20 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
 }
 /**
  * Runs every factory in `order`, awaiting those that return a promise, so each value is made before
- * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails.
- */ async function resolveProviders(container, providers, order) {
+ * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails. With `control`,
+ * it makes no further value once the app is stopping.
+ */ async function resolveProviders(container, providers, order, control) {
     for (const token of order){
         const provider = providers.get(token);
         if (!provider || !isFactoryProvider(provider)) continue;
+        if (control?.stopped()) return;
+        control?.pending(tokenName(token));
         try {
             await container.getAsync(token);
         } catch (error) {
             throw providerFailure(token, error);
+        } finally{
+            control?.pending(undefined);
         }
     }
 }
@@ -4941,6 +5049,7 @@ exports.prepareHandlerStages = prepareHandlerStages;
 exports.prepareThemes = prepareThemes;
 exports.providerMap = providerMap;
 exports.reachableClasses = reachableClasses;
+exports.recordInstanceContainers = recordInstanceContainers;
 exports.registerClientTheme = registerClientTheme;
 exports.registerCommands = registerCommands;
 exports.registrationKey = registrationKey;

package/dist/cjs/_shared/{sharded-cooldown-store-BdAUTdYs.cjs → sharded-cooldown-store-CsJJyCZd.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var node_crypto = require('node:crypto');
-var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
+var controller_decorator = require('./controller.decorator-XKMlcUZz.cjs');
 
 /** The `fatal` code of a shard whose app MeoCord refused, which every shard would refuse alike. */ const REFUSED_CODE = 'Refused';
 /** Whether an IPC message is one of MeoCord's own, rather than one of discord.js's. */ function isShardMessage(message) {
@@ -9,7 +9,10 @@ var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
 }
 
 /** Set by discord.js in every process its ShardingManager spawns. */ const SHARDING_MANAGER_ENV = 'SHARDING_MANAGER';
-/** Whether this process was spawned as a shard by a sharding manager. */ function isShardProcess(env = process.env) {
+/**
+ * Whether a process with `env` was spawned as a shard by a sharding manager. Read before anything builds a
+ * `ShardingManager`, whose constructor writes the variable into its own process too.
+ */ function isShardProcess(env) {
     return env[SHARDING_MANAGER_ENV] !== undefined;
 }
 
@@ -21,10 +24,10 @@ var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
     return env.NODE_ENV !== 'development' || config.sharding.development === true;
 }
 /**
- * The role of this process: a shard when a manager spawned it, the manager when process sharding is on,
- * and otherwise a single process running every shard it has.
- */ function shardingRole(config, env = process.env) {
-    if (isShardProcess(env)) return 'shard';
+ * The role of this process: a shard when a manager spawned it, as `shard` says, the manager when process sharding is
+ * on, and otherwise a single process running every shard it has.
+ */ function shardingRole(config, shard, env = process.env) {
+    if (shard) return 'shard';
     return processShardingEnabled(config, env) ? 'manager' : 'single';
 }
 /**
@@ -68,7 +71,7 @@ var controller_decorator = require('./controller.decorator-CRn9kWob.cjs');
  * never held forever. MeoCord itself fails the call after `cooldownStoreTimeoutMs`, a second by default.
  */ const SHARDED_COOLDOWN_ABANDON_MS = 30000;
 /** A shard's channel to its manager, or none outside process sharding. */ function managerChannel() {
-    return isShardProcess() && typeof process.send === 'function' ? channelOver(process) : undefined;
+    return isShardProcess(process.env) && typeof process.send === 'function' ? channelOver(process) : undefined;
 }
 /**
  * The channel over a process's IPC. A send on a closed channel does not throw: without a callback, Node raises an