@azurioh/discord-kernel 0.1.0

package/src/discord/command/create-command.ts

@@ -0,0 +1,431 @@
+import {
+	type ChatInputCommandInteraction,
+	InteractionContextType,
+	type LocalizationMap,
+	MessageFlags,
+	SlashCommandBuilder,
+	type SlashCommandSubcommandBuilder,
+} from "discord.js";
+import { resolveRouteOptions, respondWithSuggestions } from "@/discord/command/autocomplete";
+import { type Context, createContext, sendEmbed } from "@/discord/command/context";
+import type { Guard } from "@/discord/command/guard";
+import type { Options, Values } from "@/discord/command/options";
+import type { CommandRuntime, SlashCommand } from "@/discord/command/types";
+import { CORE_MESSAGES } from "@/discord/i18n";
+import { type PermissionBit, resolvePermissions } from "@/discord/permissions";
+import { BusinessError, createIncidentRef } from "@/errors";
+import { type Locale, type LocalizedText, resolveLocale } from "@/i18n";
+
+export interface SubcommandDef<O extends Options> {
+	description: string;
+	/** Translated names, keyed by Discord locale (e.g. `{ fr: "ajouter" }`). */
+	nameLocalizations?: LocalizationMap;
+	/** Translated descriptions, keyed by Discord locale. */
+	descriptionLocalizations?: LocalizationMap;
+	options?: O;
+	guard?: Guard;
+	/** Fallback message shown for unexpected (non-business) errors. */
+	fallbackError?: LocalizedText;
+	/** Defer the reply before running the handler (for work that may exceed 3s). */
+	defer?: boolean;
+	/** Whether replies (and the defer) are ephemeral. Defaults to true. */
+	ephemeral?: boolean;
+	handler: (ctx: Context<O>) => Promise<void>;
+}
+
+/**
+ * Type-erased subcommand. `createSubCommand()` captures the per-subcommand option
+ * generic `O` inside `invoke`, so a single command can hold subcommands with
+ * differing option shapes in one record without leaking `any`.
+ */
+export interface CompiledSubcommand {
+	description: string;
+	nameLocalizations?: LocalizationMap;
+	descriptionLocalizations?: LocalizationMap;
+	guard?: Guard;
+	fallbackError?: LocalizedText;
+	defer: boolean;
+	ephemeral: boolean;
+	options: Options;
+	invoke(ctx: Context<Options>): Promise<void>;
+}
+
+export function createSubCommand<O extends Options>(def: SubcommandDef<O>): CompiledSubcommand {
+	return {
+		description: def.description,
+		nameLocalizations: def.nameLocalizations,
+		descriptionLocalizations: def.descriptionLocalizations,
+		guard: def.guard,
+		fallbackError: def.fallbackError,
+		defer: def.defer ?? false,
+		ephemeral: def.ephemeral ?? true,
+		options: def.options ?? {},
+		invoke: (ctx) => def.handler(ctx as Context<O>),
+	};
+}
+
+interface GroupDef {
+	description: string;
+	nameLocalizations?: LocalizationMap;
+	descriptionLocalizations?: LocalizationMap;
+	subcommands: Record<string, CompiledSubcommand>;
+}
+
+/**
+ * A command is either *flat* (a single `handler`, like `/ping`) or *grouped*
+ * (`subcommands`/`groups`, like `/notes add`). Provide `handler` for the
+ * former; `handler` takes precedence over `subcommands`/`groups` if both are set.
+ */
+export interface CommandDef<O extends Options = Options> {
+	name: string;
+	description: string;
+	/** Translated names, keyed by Discord locale (e.g. `{ fr: "notes" }`). */
+	nameLocalizations?: LocalizationMap;
+	/** Translated descriptions, keyed by Discord locale. */
+	descriptionLocalizations?: LocalizationMap;
+	guard?: Guard;
+	/**
+	 * Permissions a member must hold for Discord to *show* the command. This is a
+	 * display filter, never a security boundary: a server admin can override it in
+	 * the Integrations UI, so always pair it with a guard (see `permission-guard.ts`).
+	 * Only meaningful on the root command — Discord has no per-subcommand equivalent.
+	 */
+	defaultMemberPermissions?: readonly PermissionBit[];
+	/** Restrict the command to guild contexts (no DM, no user-app install). */
+	guildOnly?: boolean;
+	/** Restrict deployment to specific guild(s); omit to deploy globally (all servers). */
+	guildIds?: readonly string[];
+	/** Flat command: typed options for the single handler. */
+	options?: O;
+	/** Flat command: defer the reply before running the handler. */
+	defer?: boolean;
+	/** Flat command: whether replies (and the defer) are ephemeral. Defaults to true. */
+	ephemeral?: boolean;
+	/** Flat command: fallback message for unexpected errors. */
+	fallbackError?: LocalizedText;
+	/** Flat command: the single handler invoked when the command runs. */
+	handler?: (ctx: Context<O>) => Promise<void>;
+	/** Grouped command: named subcommands. */
+	subcommands?: Record<string, CompiledSubcommand>;
+	/** Grouped command: named subcommand groups. */
+	groups?: Record<string, GroupDef>;
+}
+
+interface SubcommandContainer {
+	addSubcommand(
+		input: (sub: SlashCommandSubcommandBuilder) => SlashCommandSubcommandBuilder,
+	): unknown;
+}
+
+/** Resolve the reply locale for an interaction handled outside `createContext`. */
+function interactionLocale(
+	interaction: ChatInputCommandInteraction,
+	runtime: CommandRuntime,
+): Locale {
+	return resolveLocale(
+		[interaction.locale, interaction.guildLocale],
+		runtime.translator.defaultLocale,
+	);
+}
+
+/**
+ * The key a subcommand is stored and looked up under. Exported 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;
+}
+
+/**
+ * The root-level settings, split out of {@link CommandDef} so applying them does
+ * not drag the option generic `O` along (a `CommandDef<O>` is not assignable to
+ * a `CommandDef<Options>` — its handler is contravariant in the options).
+ */
+interface RootSettings {
+	nameLocalizations?: LocalizationMap;
+	descriptionLocalizations?: LocalizationMap;
+	defaultMemberPermissions?: readonly PermissionBit[];
+	guildOnly?: boolean;
+}
+
+/**
+ * Apply the settings that only exist on the root command: localisations, the
+ * visibility filter and the context restriction.
+ *
+ * `defaultMemberPermissions` is resolved from flags into the single bitfield the
+ * API expects. An empty array is meaningful — it means "administrators only" to
+ * Discord — so it is passed through rather than skipped.
+ */
+function applyRootSettings(builder: SlashCommandBuilder, def: RootSettings): void {
+	if (def.nameLocalizations) {
+		builder.setNameLocalizations(def.nameLocalizations);
+	}
+	if (def.descriptionLocalizations) {
+		builder.setDescriptionLocalizations(def.descriptionLocalizations);
+	}
+	if (def.defaultMemberPermissions) {
+		builder.setDefaultMemberPermissions(resolvePermissions(def.defaultMemberPermissions));
+	}
+	if (def.guildOnly) {
+		builder.setContexts(InteractionContextType.Guild);
+	}
+}
+
+function applySubcommand(
+	container: SubcommandContainer,
+	name: string,
+	def: CompiledSubcommand,
+): void {
+	container.addSubcommand((subBuilder) => {
+		subBuilder.setName(name).setDescription(def.description);
+		if (def.nameLocalizations) {
+			subBuilder.setNameLocalizations(def.nameLocalizations);
+		}
+		if (def.descriptionLocalizations) {
+			subBuilder.setDescriptionLocalizations(def.descriptionLocalizations);
+		}
+		for (const [optionName, option] of Object.entries(def.options)) {
+			option.apply(subBuilder, optionName);
+		}
+		return subBuilder;
+	});
+}
+
+function readOptions(
+	options: Options,
+	interaction: ChatInputCommandInteraction,
+): Record<string, unknown> {
+	const values: Record<string, unknown> = {};
+	for (const [name, option] of Object.entries(options)) {
+		values[name] = option.read(interaction, name);
+	}
+	return values;
+}
+
+function ephemeralReplyOptions(ephemeral: boolean): { flags?: MessageFlags.Ephemeral } {
+	if (ephemeral) {
+		return { flags: MessageFlags.Ephemeral };
+	}
+	return {};
+}
+
+/** Run a guard if present; reply with a denial and return `false` when it fails. */
+async function passesGuard(
+	interaction: ChatInputCommandInteraction,
+	guard: Guard | undefined,
+	runtime: CommandRuntime,
+): Promise<boolean> {
+	if (!guard) {
+		return true;
+	}
+	const result = await guard.check(interaction);
+	if (!result.ok) {
+		const locale = interactionLocale(interaction, runtime);
+		await interaction.reply({
+			embeds: [
+				runtime.presenter.denial(runtime.translator.resolve(locale, result.message), locale),
+			],
+			flags: MessageFlags.Ephemeral,
+		});
+		return false;
+	}
+	return true;
+}
+
+/** Read options, optionally defer, build the context and invoke the handler. */
+async function executeRoute(
+	interaction: ChatInputCommandInteraction,
+	route: CompiledSubcommand,
+	label: string,
+	runtime: CommandRuntime,
+): Promise<void> {
+	const { presenter, logger, translator } = runtime;
+	try {
+		const values = readOptions(route.options, interaction);
+		if (route.defer) {
+			await interaction.deferReply(ephemeralReplyOptions(route.ephemeral));
+		}
+		const ctx = createContext(
+			interaction,
+			values as Values<Options>,
+			route.ephemeral,
+			presenter,
+			logger,
+			translator,
+		);
+		await route.invoke(ctx);
+	} catch (error) {
+		await renderError(interaction, route, label, error, runtime);
+	}
+}
+
+async function dispatchFlat(
+	interaction: ChatInputCommandInteraction,
+	root: CompiledSubcommand,
+	runtime: CommandRuntime,
+): Promise<void> {
+	if (!(await passesGuard(interaction, root.guard, runtime))) {
+		return;
+	}
+	await executeRoute(interaction, root, interaction.commandName, runtime);
+}
+
+async function dispatchGrouped(
+	interaction: ChatInputCommandInteraction,
+	routes: Map<string, CompiledSubcommand>,
+	commandGuard: Guard | undefined,
+	runtime: CommandRuntime,
+): Promise<void> {
+	const group = interaction.options.getSubcommandGroup(false);
+	const name = interaction.options.getSubcommand();
+	const label = routeKey(group, name);
+	const route = routes.get(label);
+
+	if (!route) {
+		const locale = interactionLocale(interaction, runtime);
+		await interaction.reply({
+			embeds: [
+				runtime.presenter.error(
+					runtime.translator.translate(locale, CORE_MESSAGES.unknownSubcommand),
+					locale,
+				),
+			],
+			flags: MessageFlags.Ephemeral,
+		});
+		return;
+	}
+
+	if (!(await passesGuard(interaction, route.guard ?? commandGuard, runtime))) {
+		return;
+	}
+	await executeRoute(interaction, route, label, runtime);
+}
+
+async function renderError(
+	interaction: ChatInputCommandInteraction,
+	route: CompiledSubcommand,
+	label: string,
+	error: unknown,
+	runtime: CommandRuntime,
+): Promise<void> {
+	const { presenter, logger, translator } = runtime;
+	const locale = interactionLocale(interaction, runtime);
+	if (error instanceof BusinessError) {
+		const text = error.translation
+			? translator.translate(locale, error.translation.key, error.translation.params)
+			: error.message;
+		const embed =
+			error.severity === "warning"
+				? presenter.warning(text, locale)
+				: presenter.error(text, locale);
+		await sendEmbed(interaction, embed, route.ephemeral, logger);
+		return;
+	}
+
+	const ref = createIncidentRef();
+	logger.error(
+		{
+			command: interaction.commandName,
+			subcommand: label,
+			userId: interaction.user.id,
+			ref,
+			err: error instanceof Error ? error.message : String(error),
+			stack: error instanceof Error ? error.stack : undefined,
+		},
+		"Command handler failed",
+	);
+	await sendEmbed(
+		interaction,
+		presenter.systemError(
+			translator.resolve(locale, route.fallbackError ?? { key: CORE_MESSAGES.genericError }),
+			ref,
+			locale,
+		),
+		route.ephemeral,
+		logger,
+	);
+}
+
+/**
+ * Build a {@link SlashCommand} from a declarative definition: it produces the
+ * discord.js builder *and* the routing/guard/error pipeline. The runtime
+ * (presenter, logger) is injected per-dispatch by the command router.
+ */
+export function createCommand<O extends Options = Options>(def: CommandDef<O>): SlashCommand {
+	const builder = new SlashCommandBuilder().setName(def.name).setDescription(def.description);
+
+	// Configured before the flat/grouped branching below: both return paths share
+	// this builder, so root-level settings must not be duplicated per branch.
+	applyRootSettings(builder, def);
+
+	if (def.handler) {
+		const handler = def.handler;
+		const root: CompiledSubcommand = {
+			description: def.description,
+			guard: def.guard,
+			fallbackError: def.fallbackError,
+			defer: def.defer ?? false,
+			ephemeral: def.ephemeral ?? true,
+			options: def.options ?? {},
+			invoke: (ctx) => handler(ctx as Context<O>),
+		};
+		for (const [optionName, option] of Object.entries(root.options)) {
+			option.apply(builder, optionName);
+		}
+		return {
+			data: builder,
+			guildIds: def.guildIds,
+			dispatch: (interaction, runtime) => dispatchFlat(interaction, root, runtime),
+			autocomplete: hasAutocomplete(root.options)
+				? (interaction) => respondWithSuggestions(interaction, root.options)
+				: undefined,
+		};
+	}
+
+	const routes = new Map<string, CompiledSubcommand>();
+
+	if (def.subcommands) {
+		for (const [name, subDef] of Object.entries(def.subcommands)) {
+			applySubcommand(builder, name, subDef);
+			routes.set(name, subDef);
+		}
+	}
+
+	if (def.groups) {
+		for (const [groupName, group] of Object.entries(def.groups)) {
+			builder.addSubcommandGroup((groupBuilder) => {
+				groupBuilder.setName(groupName).setDescription(group.description);
+				if (group.nameLocalizations) {
+					groupBuilder.setNameLocalizations(group.nameLocalizations);
+				}
+				if (group.descriptionLocalizations) {
+					groupBuilder.setDescriptionLocalizations(group.descriptionLocalizations);
+				}
+				for (const [name, subDef] of Object.entries(group.subcommands)) {
+					applySubcommand(groupBuilder, name, subDef);
+				}
+				return groupBuilder;
+			});
+			for (const [name, subDef] of Object.entries(group.subcommands)) {
+				routes.set(routeKey(groupName, name), subDef);
+			}
+		}
+	}
+
+	return {
+		data: builder,
+		guildIds: def.guildIds,
+		dispatch: (interaction, runtime) => dispatchGrouped(interaction, routes, def.guard, runtime),
+		autocomplete: [...routes.values()].some((route) => hasAutocomplete(route.options))
+			? (interaction) =>
+					respondWithSuggestions(interaction, resolveRouteOptions(interaction, routes, null))
+			: undefined,
+	};
+}
+
+/** Whether any option of a route declares a resolver, so the seam stays absent otherwise. */
+function hasAutocomplete(options: Options): boolean {
+	return Object.values(options).some((option) => option.autocomplete !== undefined);
+}

package/src/discord/command/create-context-menu-command.ts

@@ -0,0 +1,227 @@
+import {
+	ApplicationCommandType,
+	ContextMenuCommandBuilder,
+	type ContextMenuCommandInteraction,
+	type EmbedBuilder,
+	InteractionContextType,
+	type LocalizationMap,
+	type Message,
+	MessageFlags,
+	type User,
+} from "discord.js";
+import { ContextMenuTargetError } from "@/discord/command/errors";
+import type { Guard } from "@/discord/command/guard";
+import type { CommandRuntime, ContextMenuCommand } from "@/discord/command/types";
+import { CORE_MESSAGES } from "@/discord/i18n";
+import { type PermissionBit, resolvePermissions } from "@/discord/permissions";
+import { BusinessError, createIncidentRef } from "@/errors";
+import { type Locale, type LocalizedText, resolveLocale, type TranslationParams } from "@/i18n";
+import type { Logger } from "@/logger";
+
+/**
+ * Context-menu commands: the entries a user reaches by right-clicking a member
+ * ("user" target) or a message ("message" target), under the Apps submenu.
+ *
+ * They are declared here rather than through `createCommand` because they are a
+ * different application command type: no name is typed, no options are parsed —
+ * the interaction carries the clicked target instead. Everything else (guards,
+ * permissions, error rendering) mirrors the slash-command pipeline so a module
+ * writes both the same way.
+ */
+
+/** The target handed to the handler, discriminated by the command's kind. */
+export interface ContextMenuTarget {
+	readonly user: User;
+	readonly message: Message;
+}
+
+export interface ContextMenuContext<K extends keyof ContextMenuTarget> {
+	readonly interaction: ContextMenuCommandInteraction;
+	/** The right-clicked member or message. */
+	readonly target: ContextMenuTarget[K];
+	/** Reply language: user's client locale → guild locale → configured default. */
+	readonly locale: Locale;
+	/** Translate a catalog key for this interaction's locale. */
+	t(key: string, params?: TranslationParams): string;
+	confirm(message: string): Promise<void>;
+	error(message: string): Promise<void>;
+	deny(message: string): Promise<void>;
+}
+
+export interface ContextMenuCommandDef<K extends keyof ContextMenuTarget> {
+	/** Displayed verbatim in the context menu, so spaces and capitals are allowed. */
+	name: string;
+	/** Which right-click surface the entry appears on. */
+	target: K;
+	nameLocalizations?: LocalizationMap;
+	guard?: Guard;
+	/** Display filter — pair it with a guard, it is not a security boundary. */
+	defaultMemberPermissions?: readonly PermissionBit[];
+	guildOnly?: boolean;
+	guildIds?: readonly string[];
+	/** Whether replies are ephemeral. Defaults to true. */
+	ephemeral?: boolean;
+	defer?: boolean;
+	fallbackError?: LocalizedText;
+	handler: (ctx: ContextMenuContext<K>) => Promise<void>;
+}
+
+const COMMAND_TYPES = {
+	user: ApplicationCommandType.User,
+	message: ApplicationCommandType.Message,
+} as const;
+
+/**
+ * Resolve the clicked target. discord.js exposes it through kind-specific
+ * getters, so the narrowing happens once here rather than in every handler.
+ *
+ * The kind cannot actually mismatch at runtime — Discord routes an interaction
+ * to the command it was registered as — but the resolver still asserts it, so a
+ * misroute surfaces as a named error instead of an undefined target reaching the
+ * handler.
+ */
+function resolveTarget<K extends keyof ContextMenuTarget>(
+	interaction: ContextMenuCommandInteraction,
+	kind: K,
+): ContextMenuTarget[K] {
+	if (kind === "user" && interaction.isUserContextMenuCommand()) {
+		return interaction.targetUser as ContextMenuTarget[K];
+	}
+	if (kind === "message" && interaction.isMessageContextMenuCommand()) {
+		return interaction.targetMessage as ContextMenuTarget[K];
+	}
+	throw new ContextMenuTargetError(interaction.commandName, kind);
+}
+
+export function createContextMenuCommand<K extends keyof ContextMenuTarget>(
+	def: ContextMenuCommandDef<K>,
+): ContextMenuCommand {
+	const ephemeral = def.ephemeral ?? true;
+	const builder = new ContextMenuCommandBuilder()
+		.setName(def.name)
+		.setType(COMMAND_TYPES[def.target]);
+
+	if (def.nameLocalizations) {
+		builder.setNameLocalizations(def.nameLocalizations);
+	}
+	if (def.defaultMemberPermissions) {
+		builder.setDefaultMemberPermissions(resolvePermissions(def.defaultMemberPermissions));
+	}
+	if (def.guildOnly) {
+		builder.setContexts(InteractionContextType.Guild);
+	}
+
+	return {
+		data: builder,
+		guildIds: def.guildIds,
+		dispatch: (interaction, runtime) => dispatch(interaction, def, ephemeral, runtime),
+	};
+}
+
+async function dispatch<K extends keyof ContextMenuTarget>(
+	interaction: ContextMenuCommandInteraction,
+	def: ContextMenuCommandDef<K>,
+	ephemeral: boolean,
+	runtime: CommandRuntime,
+): Promise<void> {
+	const { presenter, logger, translator } = runtime;
+	const locale = resolveLocale(
+		[interaction.locale, interaction.guildLocale],
+		translator.defaultLocale,
+	);
+
+	if (def.guard) {
+		const result = await def.guard.check(interaction);
+		if (!result.ok) {
+			await interaction.reply({
+				embeds: [presenter.denial(translator.resolve(locale, result.message), locale)],
+				flags: MessageFlags.Ephemeral,
+			});
+			return;
+		}
+	}
+
+	try {
+		if (def.defer) {
+			await interaction.deferReply(ephemeral ? { flags: MessageFlags.Ephemeral } : {});
+		}
+		await def.handler({
+			interaction,
+			target: resolveTarget(interaction, def.target),
+			locale,
+			t: (key, params) => translator.translate(locale, key, params),
+			confirm: (message) =>
+				send(interaction, presenter.confirmation(message, locale), ephemeral, logger),
+			error: (message) => send(interaction, presenter.error(message, locale), ephemeral, logger),
+			deny: (message) => send(interaction, presenter.denial(message, locale), ephemeral, logger),
+		});
+	} catch (error) {
+		if (error instanceof BusinessError) {
+			const text = error.translation
+				? translator.translate(locale, error.translation.key, error.translation.params)
+				: error.message;
+			const embed =
+				error.severity === "warning"
+					? presenter.warning(text, locale)
+					: presenter.error(text, locale);
+			await send(interaction, embed, ephemeral, logger);
+			return;
+		}
+		const ref = createIncidentRef();
+		logger.error(
+			{
+				command: interaction.commandName,
+				userId: interaction.user.id,
+				ref,
+				err: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : undefined,
+			},
+			"Context menu handler failed",
+		);
+		await send(
+			interaction,
+			presenter.systemError(
+				translator.resolve(locale, def.fallbackError ?? { key: CORE_MESSAGES.genericError }),
+				ref,
+				locale,
+			),
+			ephemeral,
+			logger,
+		);
+	}
+}
+
+/**
+ * Deliver an embed whatever the interaction's lifecycle state, and never throw:
+ * a failed delivery (e.g. an expired interaction) must not escape into the
+ * client's unhandled `error` event. Mirrors the command pipeline's `sendEmbed`,
+ * which is typed for chat-input interactions only.
+ */
+async function send(
+	interaction: ContextMenuCommandInteraction,
+	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: error instanceof Error ? error.message : String(error),
+			},
+			"Failed to deliver interaction response",
+		);
+	}
+}

package/src/discord/command/errors.ts

@@ -0,0 +1,22 @@
+import { ValidationError } from "@/errors";
+
+/**
+ * Raised when a slash command option is declared or read in a way discord.js
+ * cannot honour (an unsupported `choices` call, a value that fails parsing).
+ * A `ValidationError`, so the command pipeline renders it as user feedback
+ * rather than an incident.
+ */
+export class OptionValidationError extends ValidationError {}
+
+/**
+ * Raised when a context-menu interaction does not carry the target its command
+ * was declared for. Discord routes an interaction to the command it was
+ * registered as, so this signals a misregistration rather than user input —
+ * hence a plain `Error`, rendered as an incident with a reference.
+ */
+export class ContextMenuTargetError extends Error {
+	constructor(commandName: string, expected: string) {
+		super(`Context menu command "${commandName}" expected a ${expected} target.`);
+		this.name = "ContextMenuTargetError";
+	}
+}