@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/discord/command/passes-guard.ts

@@ -0,0 +1,37 @@
+import {
+	type CommandInteraction,
+	type MessageComponentInteraction,
+	MessageFlags,
+	type ModalSubmitInteraction,
+} from "discord.js";
+import type { Guard } from "@/discord/command/guard";
+import { type ReplyLocaleDeps, replyLocale } from "@/discord/interaction/reply-locale";
+import type { Presenter } from "@/discord/presenter";
+
+/**
+ * Run a command's or a component's guard, if it has one. The guard gets the
+ * reply dependencies, to word its denial in the reply language. On a denial,
+ * answer with the guard's own message (ephemeral) and return `false`, so the
+ * handler never runs.
+ */
+export async function passesGuard<
+	I extends CommandInteraction | MessageComponentInteraction | ModalSubmitInteraction,
+>(
+	interaction: I,
+	guard: Guard<I> | undefined,
+	runtime: ReplyLocaleDeps & { readonly presenter: Presenter },
+): Promise<boolean> {
+	if (!guard) {
+		return true;
+	}
+	const result = await guard.check(interaction, runtime);
+	if (result.ok) {
+		return true;
+	}
+	const locale = await replyLocale(interaction, runtime);
+	await interaction.reply({
+		embeds: [runtime.presenter.denial(runtime.translator.resolve(locale, result.message), locale)],
+		flags: MessageFlags.Ephemeral,
+	});
+	return false;
+}

package/src/discord/command/permission-guard.ts

@@ -2,7 +2,7 @@ import type { CommandInteraction } from "discord.js";
 import type { Guard, GuardResult } from "@/discord/command/guard";
 import { CORE_MESSAGES } from "@/discord/i18n";
 import { formatPermissions, missingPermissions, type PermissionBit } from "@/discord/permissions";
-import type { LocalizedText } from "@/i18n";
+import type { LocalizedText } from "@/i18n/translator";
 
 /**
  * Generic, reusable guards. They complement — never replace —

package/src/discord/command/render-command-failure.ts

@@ -0,0 +1,71 @@
+import type { CommandInteraction } from "discord.js";
+import { sendEmbed } from "@/discord/command/send-embed";
+import type { CommandRuntime } from "@/discord/command/types";
+import { CORE_MESSAGES } from "@/discord/i18n";
+import { replyLocale } from "@/discord/interaction/reply-locale";
+import { BusinessError } from "@/errors/business-error";
+import { errorMessage } from "@/errors/error-message";
+import { createIncidentRef } from "@/errors/incident-ref";
+import { resolveBusinessMessage } from "@/i18n/business-message";
+import type { LocalizedText } from "@/i18n/translator";
+
+/** How one command pipeline wants a failed handler reported. */
+export interface CommandFailure {
+	readonly error: unknown;
+	/** Whether the answer is ephemeral, as the command declared. */
+	readonly ephemeral: boolean;
+	/** Shown instead of the generic message for an unexpected error. */
+	readonly fallbackError?: LocalizedText;
+	/** Extra fields identifying the route in the incident log. */
+	readonly logFields?: Readonly<Record<string, unknown>>;
+	/** The incident log's message. */
+	readonly logMessage: string;
+}
+
+/**
+ * Answer a handler that threw. A {@link BusinessError} is user feedback: its
+ * own (translated) message, as a warning or an error by its severity, with no
+ * incident minted. Anything else is an incident: logged with a fresh
+ * reference, and answered with the fallback message carrying that reference.
+ */
+export async function renderCommandFailure(
+	interaction: CommandInteraction,
+	failure: CommandFailure,
+	runtime: CommandRuntime,
+): Promise<void> {
+	const { presenter, logger, translator } = runtime;
+	const { error, ephemeral } = failure;
+	const locale = await replyLocale(interaction, runtime);
+	if (error instanceof BusinessError) {
+		const text = resolveBusinessMessage(error, translator, locale);
+		const embed =
+			error.severity === "warning"
+				? presenter.warning(text, locale)
+				: presenter.error(text, locale);
+		await sendEmbed(interaction, embed, ephemeral, logger);
+		return;
+	}
+
+	const ref = createIncidentRef();
+	logger.error(
+		{
+			command: interaction.commandName,
+			...failure.logFields,
+			userId: interaction.user.id,
+			ref,
+			err: errorMessage(error),
+			stack: error instanceof Error ? error.stack : undefined,
+		},
+		failure.logMessage,
+	);
+	await sendEmbed(
+		interaction,
+		presenter.systemError(
+			translator.resolve(locale, failure.fallbackError ?? { key: CORE_MESSAGES.genericError }),
+			ref,
+			locale,
+		),
+		ephemeral,
+		logger,
+	);
+}

package/src/discord/command/route-key.ts

@@ -0,0 +1,9 @@
+/**
+ * The key a subcommand is stored and looked up under. Its own module because
+ * dispatch and autocomplete must agree on it: if they ever built it
+ * differently, an autocomplete inside a group would silently resolve to no
+ * options instead of failing loudly.
+ */
+export function routeKey(group: string | null, name: string): string {
+	return group ? `${group}/${name}` : name;
+}

package/src/discord/command/router.ts

@@ -1,4 +1,5 @@
-import { type Interaction, REST, Routes } from "discord.js";
+import { type CommandInteraction, type Interaction, REST, Routes } from "discord.js";
+import { sendEmbed } from "@/discord/command/send-embed";
 import type {
 	CommandRuntime,
 	ContextMenuCommand,
@@ -6,14 +7,30 @@ import type {
 	SlashCommand,
 } from "@/discord/command/types";
 import type { InteractionDispatcher } from "@/discord/interaction/interaction-router";
+import type { LocaleResolver } from "@/discord/interaction/locale-resolver";
 import type { Presenter } from "@/discord/presenter";
-import type { Translator } from "@/i18n";
+import { isModuleDisabled } from "@/discord/settings/is-module-disabled";
+import { moduleDisabledEmbed } from "@/discord/settings/module-disabled-embed";
+import type { Translator } from "@/i18n/translator";
 import type { Logger } from "@/logger";
+import type { ModuleGate } from "@/settings/system/module-gate";
 
 export interface CommandRouterDeps {
 	presenter: Presenter;
 	logger: Logger;
 	translator: Translator;
+	/**
+	 * When given, a command registered with a module does not run on a guild
+	 * where that module is disabled: the member gets the translated "disabled
+	 * on this server" message instead (FR-036).
+	 */
+	gate?: ModuleGate;
+	/**
+	 * Where every reply of the pipeline reads its language (e.g.
+	 * `createGuildLocaleResolver`, or the bot's own). Without one, the
+	 * interaction's own locales are used.
+	 */
+	localeResolver?: LocaleResolver;
 }
 
 /**
@@ -25,6 +42,8 @@ export interface CommandRouterDeps {
 export class CommandRouter implements InteractionDispatcher {
 	private readonly commands = new Map<string, SlashCommand>();
 	private readonly contextMenuCommands = new Map<string, ContextMenuCommand>();
+	/** The module each command was registered for, by command; absent means never gated. */
+	private readonly modules = new Map<DeployableCommand, string>();
 	private readonly runtime: CommandRuntime;
 
 	constructor(private readonly deps: CommandRouterDeps) {
@@ -32,19 +51,27 @@ export class CommandRouter implements InteractionDispatcher {
 			presenter: deps.presenter,
 			logger: deps.logger,
 			translator: deps.translator,
+			localeResolver: deps.localeResolver,
 		};
 	}
 
-	/** Register a command (last registration of a name wins). */
-	register(command: SlashCommand): this {
+	/**
+	 * Register a command (last registration of a name wins).
+	 *
+	 * @param moduleName - the module the command belongs to, so the gate can
+	 * skip it on guilds where that module is disabled. Omit it for a command
+	 * that always runs.
+	 */
+	register(command: SlashCommand, moduleName?: string): this {
 		this.commands.set(command.data.name, command);
+		this.remember(command, moduleName);
 		return this;
 	}
 
-	/** Register many commands at once. */
-	registerAll(commands: Iterable<SlashCommand>): this {
+	/** Register many commands at once, all of `moduleName` when given. */
+	registerAll(commands: Iterable<SlashCommand>, moduleName?: string): this {
 		for (const command of commands) {
-			this.register(command);
+			this.register(command, moduleName);
 		}
 		return this;
 	}
@@ -54,14 +81,15 @@ export class CommandRouter implements InteractionDispatcher {
 	 * slash command and a context-menu entry as distinct application command
 	 * types, and therefore lets them share a name.
 	 */
-	registerContextMenu(command: ContextMenuCommand): this {
+	registerContextMenu(command: ContextMenuCommand, moduleName?: string): this {
 		this.contextMenuCommands.set(command.data.name, command);
+		this.remember(command, moduleName);
 		return this;
 	}
 
-	registerAllContextMenus(commands: Iterable<ContextMenuCommand>): this {
+	registerAllContextMenus(commands: Iterable<ContextMenuCommand>, moduleName?: string): this {
 		for (const command of commands) {
-			this.registerContextMenu(command);
+			this.registerContextMenu(command, moduleName);
 		}
 		return this;
 	}
@@ -78,7 +106,9 @@ export class CommandRouter implements InteractionDispatcher {
 			if (!command) {
 				return false;
 			}
-			await command.dispatch(interaction, this.runtime);
+			if (await this.passesGate(interaction, command)) {
+				await command.dispatch(interaction, this.runtime);
+			}
 			return true;
 		}
 
@@ -87,13 +117,44 @@ export class CommandRouter implements InteractionDispatcher {
 			if (!command) {
 				return false;
 			}
-			await command.dispatch(interaction, this.runtime);
+			if (await this.passesGate(interaction, command)) {
+				await command.dispatch(interaction, this.runtime);
+			}
 			return true;
 		}
 
 		return false;
 	}
 
+	private remember(command: DeployableCommand, moduleName: string | undefined): void {
+		if (moduleName === undefined) {
+			this.modules.delete(command);
+		} else {
+			this.modules.set(command, moduleName);
+		}
+	}
+
+	/** Answer the member and return `false` when the command's module is disabled on the guild. */
+	private async passesGate(
+		interaction: CommandInteraction,
+		command: DeployableCommand,
+	): Promise<boolean> {
+		const disabled = await isModuleDisabled({
+			gate: this.deps.gate,
+			moduleName: this.modules.get(command),
+			guildId: interaction.guildId,
+		});
+		if (disabled) {
+			await sendEmbed(
+				interaction,
+				await moduleDisabledEmbed(interaction, this.deps),
+				true,
+				this.deps.logger,
+			);
+		}
+		return !disabled;
+	}
+
 	/**
 	 * Push every registered command to its declared scope: commands with
 	 * `guildIds` go to those guild(s) (instant availability), the rest are

package/src/discord/command/send-embed.ts

@@ -0,0 +1,42 @@
+import { type CommandInteraction, type EmbedBuilder, MessageFlags } from "discord.js";
+import { errorMessage } from "@/errors/error-message";
+import type { Logger } from "@/logger";
+
+/**
+ * Deliver an embed regardless of the interaction's lifecycle state, and never
+ * throw: a failed delivery (e.g. an expired/unknown interaction, code 10062)
+ * must not escape a handler and reach the client's unhandled `error` event,
+ * which would crash the process. Visibility on a deferred interaction is fixed
+ * at deferReply time, so editReply carries no flags.
+ *
+ * Typed on `CommandInteraction`, the base shared by chat-input and context-menu
+ * commands, so both pipelines answer through this one path.
+ */
+export async function sendEmbed(
+	interaction: CommandInteraction,
+	embed: EmbedBuilder,
+	ephemeral: boolean,
+	logger: Logger,
+): Promise<void> {
+	const flags = ephemeral ? MessageFlags.Ephemeral : undefined;
+	try {
+		if (interaction.deferred) {
+			await interaction.editReply({ embeds: [embed] });
+			return;
+		}
+		if (interaction.replied) {
+			await interaction.followUp({ embeds: [embed], flags });
+			return;
+		}
+		await interaction.reply({ embeds: [embed], flags });
+	} catch (error) {
+		logger.error(
+			{
+				commandName: interaction.commandName,
+				interactionId: interaction.id,
+				err: errorMessage(error),
+			},
+			"Failed to deliver interaction response",
+		);
+	}
+}

package/src/discord/command/types.ts

@@ -3,8 +3,9 @@ import type {
 	ChatInputCommandInteraction,
 	ContextMenuCommandInteraction,
 } from "discord.js";
+import type { LocaleResolver } from "@/discord/interaction/locale-resolver";
 import type { Presenter } from "@/discord/presenter";
-import type { Translator } from "@/i18n";
+import type { Translator } from "@/i18n/translator";
 import type { Logger } from "@/logger";
 
 /**
@@ -16,6 +17,11 @@ export interface CommandRuntime {
 	readonly presenter: Presenter;
 	readonly logger: Logger;
 	readonly translator: Translator;
+	/**
+	 * Where the pipeline reads the reply language. Without one, it uses the
+	 * interaction's own locales (`interactionLocale`).
+	 */
+	readonly localeResolver?: LocaleResolver;
 }
 
 /**

package/src/discord/components/component-access.ts

@@ -0,0 +1,20 @@
+import type { ComponentAuthorization } from "@/discord/components/component-router";
+import type { PermissionBit } from "@/discord/permissions";
+
+/** Any member may click; `because` records why that is acceptable. */
+export function openToAnyone(because: string): ComponentAuthorization {
+	return { kind: "anyone", because };
+}
+
+/** The router denies the click unless the member holds every permission. */
+export function requiresPermissions(...required: readonly PermissionBit[]): ComponentAuthorization {
+	return { kind: "permissions", required };
+}
+
+/**
+ * The decision needs per-resource state, so the handler makes it. `because`
+ * names the rule it applies, so a reviewer can go and check that it does.
+ */
+export function checkedByHandler(because: string): ComponentAuthorization {
+	return { kind: "handler", because };
+}

package/src/discord/components/component-router.ts

@@ -5,12 +5,20 @@ import {
 	MessageFlags,
 	type ModalSubmitInteraction,
 } from "discord.js";
+import type { Guard } from "@/discord/command/guard";
+import { passesGuard } from "@/discord/command/passes-guard";
 import { CORE_MESSAGES } from "@/discord/i18n";
 import type { InteractionDispatcher } from "@/discord/interaction/interaction-router";
+import type { LocaleResolver } from "@/discord/interaction/locale-resolver";
+import { replyLocale } from "@/discord/interaction/reply-locale";
 import { formatPermissions, missingPermissions, type PermissionBit } from "@/discord/permissions";
 import type { Presenter } from "@/discord/presenter";
-import { type Locale, resolveLocale, type Translator } from "@/i18n";
+import { isModuleDisabled } from "@/discord/settings/is-module-disabled";
+import { moduleDisabledEmbed } from "@/discord/settings/module-disabled-embed";
+import { errorMessage } from "@/errors/error-message";
+import type { Translator } from "@/i18n/translator";
 import type { Logger } from "@/logger";
+import type { ModuleGate } from "@/settings/system/module-gate";
 
 /**
  * Interactions a {@link ComponentHandler} can be routed: message components
@@ -26,6 +34,8 @@ export interface ComponentRuntime {
 	readonly presenter: Presenter;
 	readonly logger: Logger;
 	readonly translator: Translator;
+	/** The bot's reply-language resolver, if it gave one (see `ComponentRouterDeps`). */
+	readonly localeResolver?: LocaleResolver;
 }
 
 /**
@@ -54,24 +64,6 @@ export type ComponentAuthorization =
 	 */
 	| { readonly kind: "handler"; readonly because: string };
 
-/** Any member may click; `because` records why that is acceptable. */
-export function openToAnyone(because: string): ComponentAuthorization {
-	return { kind: "anyone", because };
-}
-
-/** The router denies the click unless the member holds every permission. */
-export function requiresPermissions(...required: readonly PermissionBit[]): ComponentAuthorization {
-	return { kind: "permissions", required };
-}
-
-/**
- * The decision needs per-resource state, so the handler makes it. `because`
- * names the rule it applies, so a reviewer can go and check that it does.
- */
-export function checkedByHandler(because: string): ComponentAuthorization {
-	return { kind: "handler", because };
-}
-
 /**
  * A persistent component handler, routed by `customId`. It claims an interaction
  * whose customId equals `customId` or starts with `${customId}:`, so dynamic
@@ -89,18 +81,32 @@ export interface ComponentHandler {
 	readonly customId: string;
 	/** Who may act on this component. Required: see {@link ComponentAuthorization}. */
 	readonly authorize: ComponentAuthorization;
+	/**
+	 * A check run after `authorize` and before the handler, as a command's
+	 * guard is: on a denial the member gets its message (ephemeral) and the
+	 * handler never runs. A guard over `BaseInteraction`, such as
+	 * `requireConfigured`, fits both a command and a component.
+	 */
+	readonly guard?: Guard<RoutableInteraction>;
 	handle(interaction: RoutableInteraction, runtime: ComponentRuntime): Promise<void> | void;
 }
 
-/** Declare a {@link ComponentHandler}. Identity helper kept for a consistent DSL. */
-export function createComponentHandler(handler: ComponentHandler): ComponentHandler {
-	return handler;
-}
-
 export interface ComponentRouterDeps {
 	presenter: Presenter;
 	logger: Logger;
 	translator: Translator;
+	/**
+	 * When given, a handler registered with a module does not run on a guild
+	 * where that module is disabled: the member gets the translated "disabled
+	 * on this server" message instead (FR-036).
+	 */
+	gate?: ModuleGate;
+	/**
+	 * Where the router's own replies (denials) read their language, also handed
+	 * to the handlers through the runtime. Without one, the interaction's own
+	 * locales are used.
+	 */
+	localeResolver?: LocaleResolver;
 }
 
 function isRoutable(interaction: Interaction): interaction is RoutableInteraction {
@@ -116,6 +122,8 @@ function isRoutable(interaction: Interaction): interaction is RoutableInteractio
  */
 export class ComponentRouter implements InteractionDispatcher {
 	private readonly handlers: ComponentHandler[] = [];
+	/** The module each handler was registered for; absent means never gated. */
+	private readonly modules = new Map<ComponentHandler, string>();
 	private readonly runtime: ComponentRuntime;
 
 	constructor(private readonly deps: ComponentRouterDeps) {
@@ -123,17 +131,27 @@ export class ComponentRouter implements InteractionDispatcher {
 			presenter: deps.presenter,
 			logger: deps.logger,
 			translator: deps.translator,
+			localeResolver: deps.localeResolver,
 		};
 	}
 
-	register(handler: ComponentHandler): this {
+	/**
+	 * @param moduleName - the module the handler belongs to, so the gate can
+	 * skip it on guilds where that module is disabled. Omit it for a handler
+	 * that always runs.
+	 */
+	register(handler: ComponentHandler, moduleName?: string): this {
 		this.handlers.push(handler);
+		if (moduleName !== undefined) {
+			this.modules.set(handler, moduleName);
+		}
 		return this;
 	}
 
-	registerAll(handlers: Iterable<ComponentHandler>): this {
+	/** Register many handlers at once, all of `moduleName` when given. */
+	registerAll(handlers: Iterable<ComponentHandler>, moduleName?: string): this {
 		for (const handler of handlers) {
-			this.register(handler);
+			this.register(handler, moduleName);
 		}
 		return this;
 	}
@@ -153,18 +171,25 @@ export class ComponentRouter implements InteractionDispatcher {
 		if (!handler) {
 			return false;
 		}
+		// First: a disabled module answers the same way whoever clicks.
+		if (!(await this.passesGate(interaction, handler))) {
+			return true;
+		}
 		// Before the handler runs, so a declared permission cannot be bypassed by a
 		// handler that forgot to check it.
 		if (!(await this.passesAuthorization(interaction, handler))) {
 			return true;
 		}
+		if (!(await passesGuard(interaction, handler.guard, this.runtime))) {
+			return true;
+		}
 		try {
 			await handler.handle(interaction, this.runtime);
 		} catch (error) {
 			this.deps.logger.error(
 				{
 					customId: interaction.customId,
-					err: error instanceof Error ? error.message : String(error),
+					err: errorMessage(error),
 				},
 				"Component handler failed",
 			);
@@ -172,6 +197,25 @@ export class ComponentRouter implements InteractionDispatcher {
 		return true;
 	}
 
+	/** Answer the member and return `false` when the handler's module is disabled on the guild. */
+	private async passesGate(
+		interaction: RoutableInteraction,
+		handler: ComponentHandler,
+	): Promise<boolean> {
+		const disabled = await isModuleDisabled({
+			gate: this.deps.gate,
+			moduleName: this.modules.get(handler),
+			guildId: interaction.guildId,
+		});
+		if (disabled) {
+			await interaction.reply({
+				embeds: [await moduleDisabledEmbed(interaction, this.deps)],
+				flags: MessageFlags.Ephemeral,
+			});
+		}
+		return !disabled;
+	}
+
 	/**
 	 * Enforce the handler's declared audience. Only `permissions` is enforceable
 	 * here — the other two kinds are statements about a decision made elsewhere,
@@ -193,7 +237,7 @@ export class ComponentRouter implements InteractionDispatcher {
 			return true;
 		}
 
-		const locale = this.localeOf(interaction);
+		const locale = await replyLocale(interaction, this.deps);
 		const message = this.deps.translator.translate(locale, CORE_MESSAGES.guardPermissionDenied, {
 			missing: formatPermissions(missing),
 		});
@@ -203,11 +247,4 @@ export class ComponentRouter implements InteractionDispatcher {
 		});
 		return false;
 	}
-
-	private localeOf(interaction: RoutableInteraction): Locale {
-		return resolveLocale(
-			[interaction.locale, interaction.guildLocale],
-			this.deps.translator.defaultLocale,
-		);
-	}
 }

package/src/discord/components/interactive-message/index.ts

@@ -1,6 +1,5 @@
 export {
 	COLLECTOR_IDLE_MS,
-	createStateStore,
 	type DisabledInteractiveMessageComponents,
 	type InteractiveMessageCollectorDeps,
 	type InteractiveMessageHandle,
@@ -9,10 +8,13 @@ export {
 	type InteractiveView,
 	mountInteractiveMessageCollector,
 	type SelectComponentContext,
-	type StateStore,
-	toMessageEditOptions,
 } from "@/discord/components/interactive-message/interactive-message-collector";
+export { toMessageEditOptions } from "@/discord/components/interactive-message/message-edit-options";
 export {
 	type InteractiveMessageOptions,
 	mountInteractiveMessage,
 } from "@/discord/components/interactive-message/mount-interactive-message";
+export {
+	createStateStore,
+	type StateStore,
+} from "@/discord/components/interactive-message/state-store";