@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/commands.js

@@ -0,0 +1,1004 @@
+import { commandArgumentMetadata, snapshotCommandArguments, } from "#sdk/internal/command-arguments";
+import { ConfigurationError } from "#sdk/errors";
+import { readCaller } from "./defects.js";
+import { MessageType } from "#sdk/messages";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import { nowMs } from "./clock.js";
+import { editDistance, unsupportedKeyHint } from "./suggest.js";
+import { identifyCommand } from "./events.js";
+const commandName = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const maxDurationMs = 2_147_483_647;
+const emptyCommandMetadata = Object.freeze([]);
+/** Default key limit of a memory cooldown store, including each router's own store */
+const defaultCooldownEntries = 10_000;
+/** How long `onReject: "reply"` stays quiet for one user and command after answering a guard denial */
+const guardFeedbackWindowMs = 5_000;
+/** Shared immutable command lookup state. Entry-point adapters own callback and error boundaries */
+export class PrefixCommandRegistry {
+    #definitions;
+    #commands;
+    #groups;
+    #groupLookup;
+    #entries;
+    #options;
+    #visibleEntries;
+    /** The router-owned cooldown store for commands that do not supply their own, shared by every router derived from one create */
+    cooldowns;
+    /** Keys whose `onReject: "reply"` feedback was already sent, shared like the cooldown store and bounded by the same limit */
+    feedback;
+    constructor(options, adapterKeys, definitions = new Map(), commands = emptyCommandMetadata, groups = Object.freeze([]), groupLookup = new Map(), entries = commands, shared) {
+        // Only the reads of the caller options are marked as application input, not building the registry
+        this.#options = readCaller(() => copyOptions(options, adapterKeys));
+        this.#definitions = definitions;
+        this.#commands = commands;
+        this.#groups = groups;
+        this.#groupLookup = groupLookup;
+        this.#entries = entries;
+        // Read the router-level cooldown options once, after the option shape has been validated
+        this.cooldowns =
+            shared?.cooldowns ??
+                createMemoryCooldownStore(readCaller(() => options.cooldowns));
+        this.feedback = shared?.feedback ?? new ExpiringKeys(this.cooldowns.maxEntries);
+    }
+    /** The configured prefix or resolver, for the adapter that runs a resolver in its own way */
+    get prefix() {
+        return this.#options.prefix;
+    }
+    /** Whether a mention of the bot also acts as a prefix */
+    get mentionPrefix() {
+        return this.#options.mentionPrefix === true;
+    }
+    /**
+     * Whether the router skips a message before any prefix work: One from a bot unless `ignoreBots` is false, or one a person did not type.
+     * Only Default and Reply messages carry typed text. Every other type is a notice Fluxer posts itself, such as a new thread's name, so an allow-list keeps future types out too.
+     * Fluxer always sends a type, so a message without one, such as a hand-written test payload, counts as typed rather than being dropped silently
+     */
+    ignores(message) {
+        const { type } = message;
+        if (type !== undefined && type !== MessageType.Default && type !== MessageType.Reply)
+            return true;
+        return this.#options.ignoreBots !== false && message.author.isBot === true;
+    }
+    derive(definitions, commands, groups, groupLookup, entries) {
+        return new PrefixCommandRegistry(this.#options, ["prefix", "parse", "ignoreBots", "caseSensitive", "mentionPrefix"], definitions, commands, groups, groupLookup, entries, { cooldowns: this.cooldowns, feedback: this.feedback });
+    }
+    /** Immutable registration-order help metadata with no callbacks or local storage references */
+    get commands() {
+        return this.#commands;
+    }
+    get groups() {
+        return this.#groups;
+    }
+    get entries() {
+        return this.#entries;
+    }
+    /**
+     * Commands and groups that help and unknown-name suggestions may reveal, in registration order.
+     * Leaves out entries registered with `hidden: true` and every entry inside a hidden group
+     */
+    get visibleEntries() {
+        if (this.#visibleEntries !== undefined)
+            return this.#visibleEntries;
+        const hiddenGroups = new Set(this.#groups.filter((group) => group.hidden === true).map((group) => JSON.stringify(group.path)));
+        const visible = this.#entries.filter((entry) => {
+            if (entry.hidden === true)
+                return false;
+            const path = entry.path ?? [entry.name];
+            for (let depth = 1; depth < path.length; depth += 1)
+                if (hiddenGroups.has(JSON.stringify(path.slice(0, depth))))
+                    return false;
+            return true;
+        });
+        this.#visibleEntries = visible.length === this.#entries.length ? this.#entries : Object.freeze(visible);
+        return this.#visibleEntries;
+    }
+    /** Retain an adapter-validated owned definition in a separate registry. Existing routers and subscriptions keep their previous definitions */
+    register(stored, options) {
+        return this.registerAtParent(stored, this.registrationParent(options));
+    }
+    /** Register an already snapshotted batch into one new registry, leaving this registry unchanged if any entry fails */
+    registerMany(stored, options) {
+        const parent = this.registrationParent(options);
+        let registry = this;
+        for (const definition of stored)
+            registry = registry.registerAtParent(definition, parent);
+        return registry;
+    }
+    registerAtParent(stored, parent) {
+        const keys = this.registrationKeys(stored, parent);
+        const definitions = new Map(this.#definitions);
+        for (const key of keys)
+            definitions.set(key, stored);
+        const metadata = commandMetadata(stored, parent);
+        return this.derive(definitions, Object.freeze([...this.#commands, metadata]), this.#groups, this.#groupLookup, Object.freeze([...this.#entries, metadata]));
+    }
+    registerGroup(value, options) {
+        const definition = readCaller(() => {
+            validateCommandShape(value, ["name", "aliases", "description", "hidden"]);
+            const aliases = value.aliases;
+            const description = value.description;
+            const hidden = value.hidden;
+            return snapshotCommandDefinition({
+                name: value.name,
+                ...(aliases === undefined ? {} : { aliases }),
+                ...(description === undefined ? {} : { description }),
+                ...(hidden === undefined ? {} : { hidden }),
+            });
+        });
+        const parent = this.registrationParent(options);
+        const keys = this.registrationKeys(definition, parent);
+        const metadata = Object.freeze({
+            ...definition,
+            kind: "group",
+            path: Object.freeze([...parent, definition.name]),
+        });
+        const lookup = new Map(this.#groupLookup);
+        for (const key of keys)
+            lookup.set(key, metadata);
+        return this.derive(this.#definitions, this.#commands, Object.freeze([...this.#groups, metadata]), lookup, Object.freeze([...this.#entries, metadata]));
+    }
+    /** Match a message against the prefixes the adapter resolved for it, then consume groups and parse the command */
+    resolve(message, prefixes) {
+        if (this.ignores(message))
+            return undefined;
+        const prefix = this.matchPrefix(message, prefixes);
+        if (prefix === undefined)
+            return undefined;
+        let source = message.content.slice(prefix.length);
+        let parent = Object.freeze([]);
+        for (;;) {
+            const suffix = source.trimStart();
+            const segment = /^(\S+)(?:\s+|$)/.exec(suffix);
+            const group = segment === null ? undefined : this.#groupLookup.get(this.lookupKey(parent, segment[1]));
+            if (group === undefined)
+                break;
+            parent = group.path;
+            source = suffix.slice(segment[0].length);
+            if (source.length === 0)
+                return Object.freeze({
+                    prefix,
+                    unmatched: Object.freeze({ _tag: "CommandMissingSubcommand", path: parent }),
+                });
+        }
+        const grouped = parent.length === 0 ? {} : { path: parent };
+        const input = Object.freeze({
+            message,
+            prefix,
+            source,
+            ...grouped,
+        });
+        const parsed = this.#options.parse === undefined ? defaultParse(input) : this.#options.parse(input);
+        if (parsed === undefined || isParseRejection(parsed)) {
+            const reason = parsed === undefined ? undefined : copyParseRejection(parsed);
+            return Object.freeze({
+                prefix,
+                unmatched: Object.freeze({
+                    _tag: "CommandParserRejected",
+                    ...(reason === undefined ? {} : { reason }),
+                    ...grouped,
+                }),
+            });
+        }
+        const parse = copyParse(parsed);
+        const definition = this.#definitions.get(this.lookupKey(parent, parse.name));
+        if (definition === undefined) {
+            const suggestion = this.closestName(parent, parse.name);
+            return Object.freeze({
+                prefix,
+                unmatched: Object.freeze({
+                    _tag: "CommandUnknownName",
+                    name: parse.name,
+                    ...(suggestion === undefined ? {} : { suggestion }),
+                    ...grouped,
+                }),
+            });
+        }
+        return Object.freeze({
+            definition,
+            prefix,
+            parse,
+            ...(parent.length === 0 ? {} : { path: Object.freeze([...parent, definition.name]) }),
+        });
+    }
+    registrationParent(options) {
+        if (options === undefined)
+            return Object.freeze([]);
+        const path = readCaller(() => {
+            validateObjectShape(options, ["group"], "command", "registration options");
+            const group = options.group;
+            return group === undefined ? Object.freeze([]) : copyCommandGroupPath(group, "command");
+        });
+        if (path.length > 0 && !this.#groups.some((group) => sameCommandPath(group.path, path)))
+            throw new ConfigurationError("command", 'The registration option "group" must be the path of a registered group, using group names rather than aliases', { hint: 'Register the parent group first, then pass its full path, such as ["admin", "roles"]' });
+        return path;
+    }
+    registrationKeys(value, parent) {
+        const names = [value.name, ...(value.aliases ?? [])];
+        const keys = names.map((name) => this.lookupKey(parent, name));
+        if (new Set(keys).size !== keys.length)
+            throw new ConfigurationError("aliases", `The name and aliases of ${value.name} must all be different`);
+        const taken = keys.findIndex((key) => this.#definitions.has(key) || this.#groupLookup.has(key));
+        if (taken !== -1)
+            throw new ConfigurationError("aliases", `The name or alias ${JSON.stringify(names[taken])} of ${value.name} is already used by another command or group at the same level`, { hint: "Choose a different name or alias" });
+        return keys;
+    }
+    lookupKey(parent, name) {
+        return JSON.stringify([...parent, this.normalize(name)]);
+    }
+    /**
+     * The visible registered command or group name in this parent closest to an unknown name, within a bounded edit
+     * distance: At most one edit for names up to four characters and two edits for longer names, preferring the earliest
+     * registration. Hidden entries and entries inside hidden groups are never suggested
+     */
+    closestName(parent, name) {
+        const wanted = this.normalize(name);
+        const limit = wanted.length <= 4 ? 1 : 2;
+        let best;
+        for (const entry of this.visibleEntries) {
+            const path = entry.path ?? [entry.name];
+            if (!sameCommandPath(path.slice(0, -1), parent))
+                continue;
+            for (const candidate of [entry.name, ...(entry.aliases ?? [])]) {
+                const distance = editDistance(wanted, this.normalize(candidate), limit);
+                if (distance <= limit && (best === undefined || distance < best.distance))
+                    best = { name: entry.name, distance };
+            }
+        }
+        return best?.name;
+    }
+    matchPrefix(message, resolved) {
+        const prefixes = typeof resolved === "string" ? [resolved] : resolved;
+        if (!Array.isArray(prefixes)) {
+            if (prefixes === undefined)
+                return undefined;
+            throw new ConfigurationError("prefix", "A prefix resolver must return a string, string array or undefined");
+        }
+        const values = copyNonemptyStringArray(prefixes, "prefix");
+        let selected;
+        for (const prefix of values)
+            if (message.content.startsWith(prefix) && (selected === undefined || prefix.length > selected.length))
+                selected = prefix;
+        return selected;
+    }
+    normalize(value) {
+        return this.#options.caseSensitive === true ? value : value.toLowerCase();
+    }
+}
+/**
+ * Create one bounded local cooldown store after validating only its retention limit.
+ * Used for `commands.memoryCooldowns(options)` and for a router's own store from its `cooldowns` option
+ */
+export function createMemoryCooldownStore(options) {
+    // Only reading the caller options is marked as application input, not creating the store
+    const maxEntries = readCaller(() => {
+        if (options !== undefined)
+            validateObjectShape(options, ["maxEntries"], "maxEntries", "cooldown options");
+        const selected = options?.maxEntries;
+        return selected === undefined ? defaultCooldownEntries : selected;
+    });
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+        throw new ConfigurationError("maxEntries", 'The cooldown option "maxEntries" must be a positive safe integer');
+    return new LocalMemoryCooldownStoreOwner(maxEntries);
+}
+/** Copy a caller claim once, so the validated key and duration are the ones claimed. Other values pass unchanged */
+export function snapshotClaimInput(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const { key, durationMs } = input;
+    return { key, durationMs };
+}
+/**
+ * Keys with expiry times in one process, bounded without ever refusing a new key.
+ * Making room removes expired keys first and then the key that expires soonest
+ */
+export class ExpiringKeys {
+    maxEntries;
+    #entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    /** The expiry of an unexpired key, or undefined after removing an expired one */
+    active(key, now) {
+        const expiry = this.#entries.get(key);
+        if (expiry === undefined)
+            return undefined;
+        if (expiry > now)
+            return expiry;
+        this.#entries.delete(key);
+        return undefined;
+    }
+    /** Keep a key until expiry, making room first when a new key would exceed the limit */
+    set(key, expiry, now) {
+        if (!this.#entries.has(key) && this.#entries.size >= this.maxEntries) {
+            this.sweep(now);
+            if (this.#entries.size >= this.maxEntries) {
+                let soonest;
+                let soonestExpiry = Infinity;
+                for (const [candidate, candidateExpiry] of this.#entries)
+                    if (candidateExpiry < soonestExpiry) {
+                        soonest = candidate;
+                        soonestExpiry = candidateExpiry;
+                    }
+                if (soonest !== undefined)
+                    this.#entries.delete(soonest);
+            }
+        }
+        this.#entries.set(key, expiry);
+    }
+    /**
+     * Report whether a key is already active. Otherwise keep it until `until` and report false, so the caller acts once
+     * per active key. A time that has already passed is not kept
+     */
+    suppress(key, until, now) {
+        if (this.active(key, now) !== undefined)
+            return true;
+        if (until > now)
+            this.set(key, until, now);
+        return false;
+    }
+    /** Remove expired keys and return how many were removed */
+    sweep(now) {
+        let count = 0;
+        for (const [key, expiry] of this.#entries)
+            if (expiry <= now) {
+                this.#entries.delete(key);
+                count += 1;
+            }
+        return count;
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}
+/** Snapshot cooldown fields before validation, retaining only the intentional store and key references */
+export function snapshotCommandCooldown(value) {
+    if (value === undefined)
+        return;
+    validateObjectShape(value, ["store", "durationMs", "per", "key"], "cooldown", "cooldown");
+    const { durationMs, store, key, per } = value;
+    if (typeof durationMs !== "number" ||
+        !Number.isSafeInteger(durationMs) ||
+        durationMs < 1 ||
+        durationMs > maxDurationMs)
+        throw new ConfigurationError("cooldown", `The cooldown option "durationMs" must be a positive safe integer of at most ${maxDurationMs} ms`);
+    if (store !== undefined &&
+        (typeof store !== "object" || store === null || typeof store.claim !== "function"))
+        throw new ConfigurationError("cooldown", 'The cooldown option "store" must be an object with a claim method');
+    if (key !== undefined && typeof key !== "function")
+        throw new ConfigurationError("cooldown", 'The cooldown option "key" must be a function');
+    if (per !== undefined && per !== "user" && per !== "channel" && per !== "guild")
+        throw new ConfigurationError("cooldown", 'The cooldown option "per" must be "user", "channel" or "guild"');
+    return Object.freeze({
+        durationMs,
+        per: per ?? "user",
+        ...(store === undefined ? {} : { store }),
+        ...(key === undefined ? {} : { key }),
+    });
+}
+/** The default cooldown key suffix for one invocation, selected by per */
+export function cooldownSuffix(per, message) {
+    if (per === "channel")
+        return `channel:${message.channelId}`;
+    if (per === "guild")
+        return message.guildId === undefined ? `channel:${message.channelId}` : `guild:${message.guildId}`;
+    return `user:${message.author.id}`;
+}
+/** Validate and copy the shared definition fields once before an adapter adds its callback and cooldown references */
+export function snapshotCommandDefinition(value, keyedName) {
+    if (typeof value !== "object" || value === null)
+        throw new ConfigurationError("command", "The command must be an object");
+    const name = keyedName ?? value.name;
+    if (!isCommandName(name))
+        throw new ConfigurationError("command", "Command names must use ASCII letters, numbers, `_` or `-` and begin alphanumerically");
+    const { aliases: sourceAliases, description, usage, hidden, arguments: sourceArguments } = value;
+    const aliases = sourceAliases === undefined ? undefined : copyCommandNames(sourceAliases, "aliases");
+    if (description !== undefined && typeof description !== "string")
+        throw new ConfigurationError("command", "Command description must be a string when supplied");
+    if (usage !== undefined && typeof usage !== "string")
+        throw new ConfigurationError("command", "Command usage must be a string when supplied");
+    if (hidden !== undefined && typeof hidden !== "boolean")
+        throw new ConfigurationError("command", "Command hidden must be a boolean when supplied");
+    const argumentsSchema = snapshotCommandArguments(sourceArguments);
+    return Object.freeze({
+        name,
+        ...(aliases === undefined ? {} : { aliases }),
+        ...(description === undefined ? {} : { description }),
+        ...(usage === undefined ? {} : { usage }),
+        ...(hidden === undefined ? {} : { hidden }),
+        ...(argumentsSchema === undefined ? {} : { arguments: argumentsSchema }),
+    });
+}
+/** Validate a finite adapter command object before reading its selected public fields */
+export function validateCommandShape(value, keys) {
+    validateObjectShape(value, keys, "command", "command");
+}
+/** Reject malformed command cooldown claims without exposing caller-supplied data */
+function validateCooldownClaim(value) {
+    if (typeof value !== "object" || value === null)
+        throw new ConfigurationError("cooldown", "The cooldown store returned an invalid claim", { hint: claimHint });
+    const claim = value;
+    if ((claim._tag === "CooldownAcquired" || claim._tag === "CooldownActive") &&
+        typeof claim.retryAtMs === "number" &&
+        Number.isSafeInteger(claim.retryAtMs))
+        return;
+    throw new ConfigurationError("cooldown", "The cooldown store returned an invalid claim", { hint: claimHint });
+}
+const claimHint = 'A cooldown store claim must return { _tag: "CooldownAcquired" } or { _tag: "CooldownActive" } with a safe integer retryAtMs';
+/** Validate and namespace a caller-selected cooldown key before a store sees it */
+export function cooldownRequest(commandName, key, durationMs) {
+    if (typeof key !== "string" || key.length === 0)
+        throw new ConfigurationError("cooldown", "A cooldown key must be a nonempty string");
+    return Object.freeze({ key: JSON.stringify([commandName, key]), durationMs });
+}
+/** Convert only expected configuration exceptions into the Effect error channel. Other exceptions remain defects */
+export function configurationEffect(thunk) {
+    return Effect.try({
+        try: thunk,
+        catch: (error) => {
+            if (error instanceof ConfigurationError)
+                return error;
+            throw error;
+        },
+    });
+}
+/** Why a command did not run, for its Debug record. Never includes the rejected argument text */
+function rejectionText(rejection, now) {
+    switch (rejection._tag) {
+        case "CommandGuardRejected":
+            return "a guard denied it";
+        case "CommandCooldownActive":
+            return `its cooldown is active for another ${Math.max(0, rejection.retryAtMs - now)} ms`;
+        case "CommandArgumentRejected":
+            if (rejection.reason === "Unexpected")
+                return "it received more arguments than it accepts";
+            if (rejection.reason === "Missing")
+                return `the argument ${rejection.argument} is missing`;
+            if (rejection.reason === "Ambiguous")
+                return `the argument ${rejection.argument} matches more than one option`;
+            return `the argument ${rejection.argument} is invalid`;
+    }
+}
+/** Unmatched reasons in plain words for the Debug record */
+const unmatchedText = {
+    CommandUnknownName: "A message used the command prefix with a name that matches no command",
+    CommandMissingSubcommand: "A message named a command group without a subcommand",
+    CommandParserRejected: "A message used the command prefix, but the parser found no command in it",
+};
+/** Command routers keep up with bursts: Several commands run at once and overflow drops the oldest waiting message */
+const routerDefaults = Object.freeze({ concurrency: 8, overflow: "dropOldest" });
+/** Subscription options for an attached router: Its defaults, then each defined caller setting. An explicit undefined
+ * keeps the default. The onError option is removed because the router reports command failures through its own hook queue.
+ * A non-object value passes through unchanged so client.on rejects it with its usual ConfigurationError
+ */
+export function routerSubscriptionOptions(options) {
+    if (options === undefined)
+        return routerDefaults;
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        return options;
+    const selected = { ...routerDefaults };
+    for (const [key, value] of Object.entries(options))
+        if (key !== "onError" && value !== undefined)
+            selected[key] = value;
+    return Object.freeze(selected);
+}
+/** Validate a guard verdict: `true` allows, `false` denies without a reason and `{ deny }` denies with one */
+function guardVerdict(value) {
+    if (value === true)
+        return true;
+    if (value === false)
+        return {};
+    if (typeof value === "object" &&
+        value !== null &&
+        typeof value.deny === "string" &&
+        value.deny.length > 0)
+        return { reason: value.deny };
+    throw new ConfigurationError("command", "A command guard must return a boolean or { deny: string }");
+}
+/** Prefixes to try for one message: The configured or resolved prefixes, plus the bot mention when enabled */
+function prefixesFor(registry, message, adapter) {
+    return Effect.gen(function* () {
+        const source = registry.prefix;
+        const prefixes = typeof source === "function" ? yield* adapter.prefix(source, message) : source;
+        if (!registry.mentionPrefix || adapter.selfId === undefined || prefixes === undefined)
+            return prefixes;
+        if (!message.content.startsWith("<@"))
+            return prefixes;
+        const id = yield* adapter.selfId();
+        if (id === undefined)
+            return prefixes;
+        const listed = typeof prefixes === "string" ? [prefixes] : Array.isArray(prefixes) ? prefixes : undefined;
+        // A malformed resolver value stays as it is, so resolve rejects it with the usual ConfigurationError
+        return listed === undefined ? prefixes : [...listed, `<@${id}>`, `<@!${id}>`];
+    });
+}
+/** Dispatch one resolved command through the caller's Effect runtime without a queue, send or retry */
+export function dispatchCommand(registry, message, adapter) {
+    const active = () => adapter.active === undefined
+        ? Effect.void
+        : Effect.suspend(() => (adapter.active() ? Effect.void : Effect.interrupt));
+    /**
+     * Log a rejection and give its feedback. A `"reply"` answers once per limit key while that key is active, so repeated
+     * attempts do not make the bot repeat itself. Application callbacks receive every rejection
+     */
+    const reject = (definition, context, rejection, limit) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const selected = adapter.reject === undefined
+            ? undefined
+            : adapter.feedback === undefined
+                ? "callback"
+                : adapter.feedback(definition);
+        // A false guard has no automatic reply, but custom callbacks still receive every rejection
+        const feedback = selected === "reply" && rejection._tag === "CommandGuardRejected" && rejection.reason === undefined
+            ? undefined
+            : selected;
+        const suppressed = feedback === "reply" &&
+            limit !== undefined &&
+            registry.feedback.suppress(limit.key, limit.until(now), now);
+        adapter.logger?.drop("commandRejections", {
+            level: "debug",
+            category: "commands",
+            code: "commands.rejected",
+            message: `Command ${definition.name} did not run because ${rejectionText(rejection, now)}${feedback === undefined
+                ? ""
+                : suppressed
+                    ? ". No reply was sent because the same rejection was answered recently"
+                    : feedback === "reply"
+                        ? ". A reply explains why"
+                        : ". The onReject callback was called"}`,
+            command: definition.name,
+            fields: {
+                rejection: rejection._tag,
+                ...(rejection._tag === "CommandArgumentRejected" ? { argument: rejection.argument } : {}),
+                ...(suppressed ? { feedbackSuppressed: true } : {}),
+            },
+        });
+        if (feedback === undefined || suppressed)
+            return;
+        yield* adapter.reject(definition, context, rejection, now);
+    });
+    const dispatch = Effect.gen(function* () {
+        yield* active();
+        if (registry.ignores(message))
+            return;
+        const prefixes = yield* prefixesFor(registry, message, adapter);
+        const resolved = yield* configurationEffect(() => registry.resolve(message, prefixes));
+        if (resolved === undefined)
+            return;
+        if ("unmatched" in resolved) {
+            yield* active();
+            const suggestion = resolved.unmatched._tag === "CommandUnknownName" ? resolved.unmatched.suggestion : undefined;
+            const detail = resolved.unmatched._tag === "CommandMissingSubcommand"
+                ? ` (${resolved.unmatched.path.join(" ")})`
+                : resolved.unmatched._tag === "CommandParserRejected" && resolved.unmatched.reason !== undefined
+                    ? ` (${resolved.unmatched.reason})`
+                    : "";
+            adapter.logger?.drop("unmatchedCommands", {
+                level: "debug",
+                category: "commands",
+                code: "commands.unmatched",
+                message: `${unmatchedText[resolved.unmatched._tag]}${detail}${suggestion === undefined ? "" : `. The closest command is ${suggestion}`}${adapter.unmatched === undefined ? "" : ". The onUnmatched callback was called"}`,
+                fields: {
+                    reason: resolved.unmatched._tag,
+                    messageId: message.id,
+                    channelId: message.channelId,
+                    ...(suggestion === undefined ? {} : { suggestion }),
+                },
+            });
+            if (adapter.unmatched !== undefined)
+                yield* adapter.unmatched(resolved);
+            return;
+        }
+        const matched = resolved;
+        yield* identifyCommand(matched.definition.name);
+        const run = matchedCommand(matched).pipe(Effect.withSpan("fluxerly.command.execute", {
+            attributes: { "fluxerly.command": matched.definition.name },
+        }));
+        if (adapter.failed === undefined)
+            return yield* run;
+        return yield* run.pipe(Effect.catchCause((cause) => Cause.hasInterrupts(cause) ? Effect.failCause(cause) : adapter.failed(matched.definition.name, cause)));
+    });
+    if (adapter.failed === undefined)
+        return dispatch;
+    // Unmatched callbacks and custom parsers can fail outside a matched command, and they reach the same report
+    return dispatch.pipe(Effect.catchCause((cause) => Cause.hasInterrupts(cause) ? Effect.failCause(cause) : adapter.failed(undefined, cause)));
+    function matchedCommand(matched) {
+        return Effect.gen(function* () {
+            const context = adapter.context(matched);
+            yield* active();
+            let continued = false;
+            const rest = Effect.gen(function* () {
+                continued = true;
+                yield* checkedCommand(matched, context);
+            });
+            if (adapter.around === undefined)
+                return yield* rest;
+            yield* adapter.around(context, rest);
+            if (!continued)
+                adapter.logger?.log({
+                    level: "debug",
+                    category: "commands",
+                    code: "commands.middlewareStopped",
+                    message: `Command ${matched.definition.name} did not run because middleware did not continue`,
+                    command: matched.definition.name,
+                });
+        });
+    }
+    function checkedCommand(matched, context) {
+        return Effect.gen(function* () {
+            const verdict = guardVerdict(yield* adapter.guard(matched.definition, context));
+            if (verdict !== true) {
+                yield* active();
+                yield* reject(matched.definition, context, Object.freeze({
+                    _tag: "CommandGuardRejected",
+                    ...(verdict.reason === undefined ? {} : { reason: verdict.reason }),
+                }), {
+                    key: JSON.stringify(["guard", matched.path ?? [matched.definition.name], message.author.id]),
+                    until: (now) => now + guardFeedbackWindowMs,
+                });
+                return;
+            }
+            const conversion = adapter.convert === undefined ? undefined : adapter.convert(matched.definition, context);
+            if (conversion !== undefined && conversion._tag === "Rejected") {
+                yield* active();
+                yield* reject(matched.definition, context, Object.freeze({
+                    _tag: "CommandArgumentRejected",
+                    argument: conversion.argument,
+                    reason: conversion.reason,
+                }));
+                return;
+            }
+            const executionContext = conversion === undefined || adapter.executionContext === undefined
+                ? context
+                : adapter.executionContext(context, conversion.values);
+            if (adapter.cooldown !== undefined) {
+                yield* active();
+                const claimed = yield* adapter.cooldown(matched.definition, executionContext, registry.cooldowns);
+                if (claimed !== undefined) {
+                    yield* configurationEffect(() => validateCooldownClaim(claimed.claim));
+                    const claim = claimed.claim;
+                    if (claim._tag === "CooldownActive") {
+                        yield* active();
+                        yield* reject(matched.definition, context, Object.freeze({ _tag: "CommandCooldownActive", retryAtMs: claim.retryAtMs }), { key: JSON.stringify(["cooldown", claimed.key]), until: () => claim.retryAtMs });
+                        return;
+                    }
+                }
+            }
+            yield* active();
+            // Measured on the dispatch's Effect Clock, so a TestClock controls the reported duration
+            const clock = yield* Clock.Clock;
+            const startedAt = nowMs(clock);
+            yield* adapter.execute(matched.definition, executionContext);
+            adapter.logger?.log({
+                level: "debug",
+                category: "commands",
+                code: "commands.executed",
+                message: `Command ${matched.definition.name} finished`,
+                command: matched.definition.name,
+                durationMs: Math.round(nowMs(clock) - startedAt),
+            });
+        });
+    }
+}
+/**
+ * Impersonal reply text for a rejected command, used by `onReject: "reply"`.
+ * A guard denial without a reason returns undefined, so a false verdict has no generic reply.
+ * Argument rejections name the argument, what was expected and the command's usage.
+ * Cooldown replies measure the remaining time from `now`, the dispatch Clock's wall time
+ */
+export function rejectionReply(rejection, command, prefix, now) {
+    switch (rejection._tag) {
+        case "CommandGuardRejected":
+            return rejection.reason;
+        case "CommandCooldownActive": {
+            const seconds = Math.max(1, Math.ceil((rejection.retryAtMs - now) / 1_000));
+            return `This command is on cooldown. Try again in ${seconds} ${seconds === 1 ? "second" : "seconds"}`;
+        }
+        case "CommandArgumentRejected": {
+            const usage = command === undefined
+                ? ""
+                : `. Usage: ${prefix}${(command.path ?? [command.name]).join(" ")}${commandUsage(command) ? " " + commandUsage(command) : ""}`;
+            if (rejection.reason === "Unexpected")
+                return `Too many arguments${usage}`;
+            const argument = command?.arguments?.find((entry) => entry.name === rejection.argument);
+            if (rejection.reason === "Missing")
+                return `Missing ${rejection.argument}${usage}`;
+            if (rejection.reason === "Ambiguous")
+                return `The ${rejection.argument} value matches more than one option, so an ID or mention is needed${usage}`;
+            return `Invalid ${rejection.argument}${argument === undefined ? "" : `. Expected ${expectation(argument)}`}${usage}`;
+        }
+    }
+}
+/** Generated usage syntax such as `<text> [count]`, or the command's explicit usage */
+function commandUsage(command) {
+    return (command.usage ??
+        command.arguments
+            ?.map((argument) => {
+            const name = argument.name + (argument.rest ? "..." : "");
+            return argument.optional ? `[${name}]` : `<${name}>`;
+        })
+            .join(" ") ??
+        "");
+}
+function expectation(argument) {
+    const range = (unit) => argument.min !== undefined && argument.max !== undefined
+        ? ` from ${unit(argument.min)} to ${unit(argument.max)}`
+        : argument.min !== undefined
+            ? ` of at least ${unit(argument.min)}`
+            : argument.max !== undefined
+                ? ` of at most ${unit(argument.max)}`
+                : "";
+    switch (argument.type) {
+        case "integer":
+            return `a whole number${range(String)}`;
+        case "number":
+            return `a number${range(String)}`;
+        case "duration":
+            return `a duration${argument.wholeSeconds === true ? " in whole seconds" : ""} such as 10m or 1h30m${range((value) => `${value} ms`)}`;
+        case "boolean":
+            return "true or false";
+        case "id":
+            return argument.mention === undefined ? "an ID" : `an ID or ${argument.mention} mention`;
+        case "choice":
+            return `one of ${(argument.choices ?? []).join(", ")}`;
+        case "member":
+            return "a member mention or ID";
+        case "userChoice":
+            return "a listed user";
+        case "channelChoice":
+            return "a listed channel";
+        case "roleChoice":
+            return "a listed role";
+        case "custom":
+            return argument.expected ?? "a valid value";
+        case "text":
+            return "text";
+    }
+}
+/** Router option keys shared by both APIs. Each API adds its own callback keys */
+const routerOptionKeys = ["prefix", "parse", "ignoreBots", "caseSensitive", "mentionPrefix", "cooldowns"];
+/** Subscription delivery settings that a runBot commands option passes to the router's attach unchanged */
+export const botCommandDeliveryKeys = [
+    "concurrency",
+    "partition",
+    "overflow",
+    "maxPendingMessages",
+    "maxPendingBytes",
+];
+/**
+ * Check the keys of a runBot commands option before its router is created, so the hint also lists commands and onError.
+ * A key whose value looks like a command definition is explained as a command placed one level too high.
+ * Values are read through property descriptors, so no getter runs here
+ */
+export function checkBotCommandKeys(options, adapterKeys) {
+    const keys = [...routerOptionKeys, ...adapterKeys, ...botCommandDeliveryKeys, "commands", "onError"];
+    for (const key of Reflect.ownKeys(options)) {
+        if (typeof key !== "string" || keys.includes(key))
+            continue;
+        const value = Reflect.getOwnPropertyDescriptor(options, key)?.value;
+        const command = typeof value === "object" && value !== null && Object.hasOwn(value, "execute");
+        throw new ConfigurationError("commands", `Unsupported key ${JSON.stringify(key)} in the runBot commands option`, {
+            hint: command
+                ? `Put command definitions in the inner commands object, next to prefix, such as commands: { prefix: "!", commands: { ${key.length > 64 ? "name" : key}: { execute } } }`
+                : unsupportedKeyHint(key, keys, "keys"),
+        });
+    }
+}
+/**
+ * Validate the shared router settings. Adapter keys, such as callbacks, are allowed here and validated by the adapter.
+ * The `cooldowns` option is allowed but not copied, because the registry reads it once to create its own store
+ */
+function copyOptions(input, adapterKeys) {
+    validateObjectShape(input, [...routerOptionKeys, ...adapterKeys], "commands", "prefix command options");
+    const value = input;
+    if (value.prefix === undefined)
+        throw new ConfigurationError("prefix", 'The option "prefix" is required', {
+            hint: 'Set the text that starts a command, such as prefix: "!"',
+        });
+    if (typeof value.prefix !== "string" && !Array.isArray(value.prefix) && typeof value.prefix !== "function")
+        throw new ConfigurationError("prefix", 'The option "prefix" must be a string, an array of strings or a function');
+    if (typeof value.prefix === "string" && value.prefix.length === 0)
+        throw new ConfigurationError("prefix", 'The option "prefix" must not be empty');
+    const prefix = Array.isArray(value.prefix) ? copyNonemptyStringArray(value.prefix, "prefix") : value.prefix;
+    if (value.parse !== undefined && typeof value.parse !== "function")
+        throw new ConfigurationError("parser", 'The option "parse" must be a function');
+    if (value.ignoreBots !== undefined && typeof value.ignoreBots !== "boolean")
+        throw new ConfigurationError("commands", 'The option "ignoreBots" must be a boolean');
+    if (value.caseSensitive !== undefined && typeof value.caseSensitive !== "boolean")
+        throw new ConfigurationError("commands", 'The option "caseSensitive" must be a boolean');
+    if (value.mentionPrefix !== undefined && typeof value.mentionPrefix !== "boolean")
+        throw new ConfigurationError("commands", 'The option "mentionPrefix" must be a boolean');
+    return Object.freeze({
+        prefix,
+        ...(value.parse === undefined ? {} : { parse: value.parse }),
+        ...(value.ignoreBots === undefined ? {} : { ignoreBots: value.ignoreBots }),
+        ...(value.caseSensitive === undefined ? {} : { caseSensitive: value.caseSensitive }),
+        ...(value.mentionPrefix === undefined ? {} : { mentionPrefix: value.mentionPrefix }),
+    });
+}
+/** Project only public metadata from an already validated owned registration snapshot */
+function commandMetadata(value, parent) {
+    const argumentsMetadata = commandArgumentMetadata(value.arguments);
+    return Object.freeze({
+        name: value.name,
+        ...(parent.length === 0 ? {} : { path: Object.freeze([...parent, value.name]) }),
+        ...(value.aliases === undefined ? {} : { aliases: value.aliases }),
+        ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.usage === undefined ? {} : { usage: value.usage }),
+        ...(value.hidden === undefined ? {} : { hidden: value.hidden }),
+        ...(argumentsMetadata === undefined ? {} : { arguments: argumentsMetadata }),
+    });
+}
+/** Validate a canonical group selector without retaining rejected caller values */
+export function copyCommandGroupPath(value, field) {
+    if (!Array.isArray(value))
+        throw new ConfigurationError(field, 'The option "group" must be an array of group names, not aliases');
+    validateArrayShape(value, field);
+    const path = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const name = value[index];
+        if (!isCommandName(name))
+            throw new ConfigurationError(field, 'The option "group" must contain group names that use ASCII letters, numbers, `_` or `-` and begin alphanumerically');
+        path.push(name);
+    }
+    return Object.freeze(path);
+}
+/** Exact canonical path comparison, independent of alias matching policy */
+export function sameCommandPath(left, right) {
+    return left.length === right.length && left.every((name, index) => name === right[index]);
+}
+/** A parser result with a reason and no name, which declines the text with an explanation instead of naming a command */
+function isParseRejection(value) {
+    return typeof value === "object" && value !== null && "reason" in value && !("name" in value);
+}
+function copyParseRejection(value) {
+    validateObjectShape(value, ["reason"], "parser", "parser rejection");
+    const reason = value.reason;
+    if (typeof reason !== "string" || reason.length === 0)
+        throw new ConfigurationError("parser", "A parser rejection must have a nonempty string reason");
+    return reason;
+}
+function copyParse(value) {
+    validateObjectShape(value, ["name", "args", "rawArgs"], "parser", "parser result");
+    if (!isCommandName(value.name))
+        throw new ConfigurationError("parser", "A parser must return a valid command name");
+    if (typeof value.rawArgs !== "string")
+        throw new ConfigurationError("parser", "A parser must return rawArgs as a string");
+    return Object.freeze({ name: value.name, rawArgs: value.rawArgs, args: copyStringArray(value.args, "parser") });
+}
+function defaultParse(input) {
+    const source = input.source.trimStart();
+    if (source.length === 0)
+        return undefined;
+    const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(source);
+    const name = match?.[1];
+    if (name === undefined || !isCommandName(name))
+        return undefined;
+    const rawArgs = match?.[2] ?? "";
+    const positional = rawArgs.trim();
+    return { name, rawArgs, args: positional.length === 0 ? [] : positional.split(/\s+/) };
+}
+function copyCommandNames(value, field) {
+    const names = copyStringArray(value, field);
+    for (const name of names)
+        if (!isCommandName(name))
+            throw new ConfigurationError("aliases", "Command aliases must use ASCII letters, numbers, `_` or `-` and begin alphanumerically");
+    return names;
+}
+function copyNonemptyStringArray(value, field) {
+    const values = copyStringArray(value, field);
+    if (values.length === 0)
+        throw new ConfigurationError("prefix", prefixArrayMessage);
+    for (const prefix of values)
+        if (prefix.length === 0)
+            throw new ConfigurationError("prefix", prefixArrayMessage);
+    return values;
+}
+const prefixArrayMessage = "A prefix array must contain at least one prefix, and no prefix may be empty";
+/** How array shape messages name the value they check */
+const shapeSubjects = {
+    aliases: 'The option "aliases"',
+    prefix: "The prefix list",
+    parser: 'The parser result "args"',
+    command: 'The option "group"',
+    help: 'The help option "group"',
+};
+function copyStringArray(value, field) {
+    if (!Array.isArray(value))
+        throw new ConfigurationError(field, `${shapeSubjects[field]} must be an array of strings`);
+    validateArrayShape(value, field);
+    const copied = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const entry = value[index];
+        if (typeof entry !== "string")
+            throw new ConfigurationError(field, `${shapeSubjects[field]} must contain only strings`);
+        copied.push(entry);
+    }
+    return Object.freeze(copied);
+}
+function validateObjectShape(value, keys, field, subject) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new ConfigurationError(field, `The ${subject} must be an object`);
+    for (const key of Reflect.ownKeys(value))
+        if (typeof key !== "string" || !keys.includes(key))
+            throw new ConfigurationError(field, typeof key === "string"
+                ? `Unsupported key ${JSON.stringify(key)} in the ${subject}`
+                : `The ${subject} must not have symbol keys`, {
+                hint: typeof key === "string"
+                    ? unsupportedKeyHint(key, keys, "keys")
+                    : `Supported keys are ${keys.join(", ")}`,
+            });
+}
+function validateArrayShape(value, field) {
+    for (let index = 0; index < value.length; index += 1)
+        if (!Object.hasOwn(value, index))
+            throw new ConfigurationError(field, `${shapeSubjects[field]} must not have empty slots`);
+    for (const key of Reflect.ownKeys(value)) {
+        if (key === "length")
+            continue;
+        if (typeof key !== "string" || !isArrayIndex(key, value.length))
+            throw new ConfigurationError(field, `${shapeSubjects[field]} must be a plain array without extra properties`);
+    }
+}
+function isArrayIndex(key, length) {
+    if (!/^(?:0|[1-9]\d*)$/.test(key))
+        return false;
+    const index = Number(key);
+    return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+function isCommandName(value) {
+    return typeof value === "string" && commandName.test(value);
+}
+/** A memory cooldown store that never denies a new key for capacity, evicting as ExpiringKeys describes */
+class LocalMemoryCooldownStoreOwner {
+    maxEntries;
+    #entries;
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+        this.#entries = new ExpiringKeys(maxEntries);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    claim(input, now = Date.now()) {
+        const request = validateMemoryRequest(input);
+        if (request._tag === "Failure")
+            return request;
+        const active = this.#entries.active(request.value.key, now);
+        if (active !== undefined)
+            return success(Object.freeze({ _tag: "CooldownActive", retryAtMs: active }));
+        const retryAtMs = now + request.value.durationMs;
+        this.#entries.set(request.value.key, retryAtMs, now);
+        return success(Object.freeze({ _tag: "CooldownAcquired", retryAtMs }));
+    }
+    sweep(now = Date.now()) {
+        return this.#entries.sweep(now);
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}
+function validateMemoryRequest(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return failure(new ConfigurationError("cooldown", "A cooldown claim requires an object"));
+    const request = input;
+    if (typeof request.key !== "string" || request.key.length === 0)
+        return failure(new ConfigurationError("cooldown", "A cooldown key must be a nonempty string"));
+    if (typeof request.durationMs !== "number" ||
+        !Number.isSafeInteger(request.durationMs) ||
+        request.durationMs < 1 ||
+        request.durationMs > maxDurationMs)
+        return failure(new ConfigurationError("cooldown", `The cooldown option "durationMs" must be a positive safe integer of at most ${maxDurationMs} ms`));
+    return success(Object.freeze({ key: request.key, durationMs: request.durationMs }));
+}
+function success(value) {
+    return Object.freeze({ _tag: "Success", value });
+}
+function failure(error) {
+    return Object.freeze({ _tag: "Failure", error });
+}
+//# sourceMappingURL=commands.js.map