@azurioh/discord-kernel 0.1.0

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

@@ -0,0 +1,74 @@
+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";
+
+/**
+ * Generic, reusable guards. They complement — never replace —
+ * `defaultMemberPermissions` on a command: that field only *hides* the command
+ * in the Discord client, and a server admin can override it in the Integrations
+ * UI. The guard is the enforcement that actually runs server-side.
+ */
+
+const ALLOW: GuardResult = { ok: true };
+
+/**
+ * Deny unless the member holds every permission in `required`.
+ *
+ * `interaction.memberPermissions` is `null` outside a guild; that is a denial,
+ * since an unknown permission set cannot be treated as a granted one.
+ */
+export function createPermissionGuard(
+	required: readonly PermissionBit[],
+	denyMessage?: LocalizedText,
+): Guard {
+	return {
+		check(interaction: CommandInteraction): GuardResult {
+			const missing = missingPermissions(interaction.memberPermissions, required);
+			if (missing.length === 0) {
+				return ALLOW;
+			}
+			return {
+				ok: false,
+				message: denyMessage ?? {
+					key: CORE_MESSAGES.guardPermissionDenied,
+					params: { missing: formatPermissions(missing) },
+				},
+			};
+		},
+	};
+}
+
+/**
+ * Deny unless the member holds one of `roleIds`.
+ *
+ * Outside a guild there is no member and therefore no role: deny. The member's
+ * role cache is authoritative here because `interactionCreate` always carries a
+ * fully resolved member object for guild interactions.
+ */
+export function createRoleGuard(roleIds: readonly string[], denyMessage?: LocalizedText): Guard {
+	return {
+		check(interaction: CommandInteraction): GuardResult {
+			const member = interaction.member;
+			if (!member || !interaction.inCachedGuild()) {
+				return { ok: false, message: denyMessage ?? { key: CORE_MESSAGES.guardGuildOnly } };
+			}
+			const held = interaction.member.roles.cache;
+			if (roleIds.some((roleId) => held.has(roleId))) {
+				return ALLOW;
+			}
+			return { ok: false, message: denyMessage ?? { key: CORE_MESSAGES.guardRoleDenied } };
+		},
+	};
+}
+
+/** Deny outside a guild, so a handler can rely on the guild context existing. */
+export const guildOnlyGuard: Guard = {
+	check(interaction: CommandInteraction): GuardResult {
+		if (interaction.inGuild()) {
+			return ALLOW;
+		}
+		return { ok: false, message: { key: CORE_MESSAGES.guardGuildOnly } };
+	},
+};

package/src/discord/command/router.ts

@@ -0,0 +1,142 @@
+import { type Interaction, REST, Routes } from "discord.js";
+import type {
+	CommandRuntime,
+	ContextMenuCommand,
+	DeployableCommand,
+	SlashCommand,
+} from "@/discord/command/types";
+import type { InteractionDispatcher } from "@/discord/interaction/interaction-router";
+import type { Presenter } from "@/discord/presenter";
+import type { Translator } from "@/i18n";
+import type { Logger } from "@/logger";
+
+export interface CommandRouterDeps {
+	presenter: Presenter;
+	logger: Logger;
+	translator: Translator;
+}
+
+/**
+ * Owns the registered slash commands and dispatches chat-input interactions to
+ * them, injecting the shared {@link CommandRuntime}. Also registers the command
+ * definitions with Discord's API. It does not attach its own listener — it is an
+ * {@link InteractionDispatcher} driven by the shared {@link InteractionRouter}.
+ */
+export class CommandRouter implements InteractionDispatcher {
+	private readonly commands = new Map<string, SlashCommand>();
+	private readonly contextMenuCommands = new Map<string, ContextMenuCommand>();
+	private readonly runtime: CommandRuntime;
+
+	constructor(private readonly deps: CommandRouterDeps) {
+		this.runtime = {
+			presenter: deps.presenter,
+			logger: deps.logger,
+			translator: deps.translator,
+		};
+	}
+
+	/** Register a command (last registration of a name wins). */
+	register(command: SlashCommand): this {
+		this.commands.set(command.data.name, command);
+		return this;
+	}
+
+	/** Register many commands at once. */
+	registerAll(commands: Iterable<SlashCommand>): this {
+		for (const command of commands) {
+			this.register(command);
+		}
+		return this;
+	}
+
+	/**
+	 * Register a context-menu entry. Kept in its own map because Discord treats a
+	 * slash command and a context-menu entry as distinct application command
+	 * types, and therefore lets them share a name.
+	 */
+	registerContextMenu(command: ContextMenuCommand): this {
+		this.contextMenuCommands.set(command.data.name, command);
+		return this;
+	}
+
+	registerAllContextMenus(commands: Iterable<ContextMenuCommand>): this {
+		for (const command of commands) {
+			this.registerContextMenu(command);
+		}
+		return this;
+	}
+
+	/** Look up a registered slash command, for dispatchers that share this registry. */
+	get(name: string): SlashCommand | undefined {
+		return this.commands.get(name);
+	}
+
+	/** Claim and dispatch chat-input and context-menu commands; ignore everything else. */
+	async handle(interaction: Interaction): Promise<boolean> {
+		if (interaction.isChatInputCommand()) {
+			const command = this.commands.get(interaction.commandName);
+			if (!command) {
+				return false;
+			}
+			await command.dispatch(interaction, this.runtime);
+			return true;
+		}
+
+		if (interaction.isContextMenuCommand()) {
+			const command = this.contextMenuCommands.get(interaction.commandName);
+			if (!command) {
+				return false;
+			}
+			await command.dispatch(interaction, this.runtime);
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Push every registered command to its declared scope: commands with
+	 * `guildIds` go to those guild(s) (instant availability), the rest are
+	 * deployed globally (available on every server, slower to propagate). The
+	 * global scope is always synced — even when empty — so stale global commands
+	 * are pruned. Returns the number of commands deployed.
+	 */
+	async deployCommands(token: string, clientId: string): Promise<number> {
+		const rest = new REST({ version: "10" }).setToken(token);
+		const global: unknown[] = [];
+		const byGuild = new Map<string, unknown[]>();
+		let deployed = 0;
+
+		const all: DeployableCommand[] = [
+			...this.commands.values(),
+			...this.contextMenuCommands.values(),
+		];
+
+		for (const command of all) {
+			const body = command.data.toJSON ? command.data.toJSON() : null;
+			if (body === null) {
+				continue;
+			}
+			deployed += 1;
+			if (command.guildIds && command.guildIds.length > 0) {
+				for (const guildId of command.guildIds) {
+					const bucket = byGuild.get(guildId) ?? [];
+					bucket.push(body);
+					byGuild.set(guildId, bucket);
+				}
+			} else {
+				global.push(body);
+			}
+		}
+
+		await rest.put(Routes.applicationCommands(clientId), { body: global });
+		this.deps.logger.info({ count: global.length }, "Global slash commands deployed");
+
+		for (const [guildId, body] of byGuild) {
+			await rest.put(Routes.applicationGuildCommands(clientId, guildId), { body });
+			this.deps.logger.info({ guildId, count: body.length }, "Guild slash commands deployed");
+		}
+
+		return deployed;
+	}
+}

package/src/discord/command/types.ts

@@ -0,0 +1,52 @@
+import type {
+	AutocompleteInteraction,
+	ChatInputCommandInteraction,
+	ContextMenuCommandInteraction,
+} from "discord.js";
+import type { Presenter } from "@/discord/presenter";
+import type { Translator } from "@/i18n";
+import type { Logger } from "@/logger";
+
+/**
+ * Per-request dependencies injected into the command pipeline by the router.
+ * Passing these at dispatch time (rather than importing singletons) keeps the
+ * framework free of global state and trivially testable.
+ */
+export interface CommandRuntime {
+	readonly presenter: Presenter;
+	readonly logger: Logger;
+	readonly translator: Translator;
+}
+
+/**
+ * The framework's slash-command contract. `data` is a discord.js builder (or
+ * anything with `.toJSON()`); `dispatch` routes an interaction using the
+ * supplied runtime. `guildIds` restricts deployment to specific guild(s); when
+ * omitted the command is deployed globally (available on every server).
+ */
+export interface SlashCommand {
+	readonly data: { name: string; toJSON?: () => unknown };
+	readonly guildIds?: readonly string[];
+	dispatch(interaction: ChatInputCommandInteraction, runtime: CommandRuntime): Promise<void>;
+	/**
+	 * Answer an autocomplete request for one of this command's options. Present
+	 * only when at least one option declares a resolver, so the dispatcher can
+	 * skip commands that never autocomplete.
+	 */
+	autocomplete?(interaction: AutocompleteInteraction): Promise<void>;
+}
+
+/**
+ * A context-menu (a.k.a. application) command: the entry a user gets by
+ * right-clicking a member or a message. It shares deployment and permissions
+ * with a slash command, but carries no name to type and no options — only the
+ * target the user clicked.
+ */
+export interface ContextMenuCommand {
+	readonly data: { name: string; toJSON?: () => unknown };
+	readonly guildIds?: readonly string[];
+	dispatch(interaction: ContextMenuCommandInteraction, runtime: CommandRuntime): Promise<void>;
+}
+
+/** Anything the command router can register and deploy to Discord. */
+export type DeployableCommand = SlashCommand | ContextMenuCommand;

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

@@ -0,0 +1,213 @@
+import {
+	type AnySelectMenuInteraction,
+	type ButtonInteraction,
+	type Interaction,
+	MessageFlags,
+	type ModalSubmitInteraction,
+} from "discord.js";
+import { CORE_MESSAGES } from "@/discord/i18n";
+import type { InteractionDispatcher } from "@/discord/interaction/interaction-router";
+import { formatPermissions, missingPermissions, type PermissionBit } from "@/discord/permissions";
+import type { Presenter } from "@/discord/presenter";
+import { type Locale, resolveLocale, type Translator } from "@/i18n";
+import type { Logger } from "@/logger";
+
+/**
+ * Interactions a {@link ComponentHandler} can be routed: message components
+ * (buttons, any select menu) and modal submissions.
+ */
+export type RoutableInteraction =
+	| ButtonInteraction
+	| AnySelectMenuInteraction
+	| ModalSubmitInteraction;
+
+/** Per-dispatch dependencies, injected by the router (mirrors `CommandRuntime`). */
+export interface ComponentRuntime {
+	readonly presenter: Presenter;
+	readonly logger: Logger;
+	readonly translator: Translator;
+}
+
+/**
+ * Who may act on a component.
+ *
+ * A command declares its audience through `defaultMemberPermissions` + a
+ * `Guard`, and `Guard` is typed on `CommandInteraction` — deliberately, so a
+ * guard cannot be attached to a button. That leaves a component with no
+ * framework-level place to state who may click it, and the only thing standing
+ * between a member and a destructive button is whether whoever wrote the
+ * handler remembered to check. Every existing handler does; nothing makes the
+ * next one.
+ *
+ * So the answer is required by the type. There is no default and no optional
+ * field: a handler that says nothing does not compile, and "anyone may click
+ * this" has to be written down and justified rather than reached by omission.
+ */
+export type ComponentAuthorization =
+	/** Any member may click. `because` is why that is safe, not decoration. */
+	| { readonly kind: "anyone"; readonly because: string }
+	/** The router denies unless the member holds every listed permission. */
+	| { readonly kind: "permissions"; readonly required: readonly PermissionBit[] }
+	/**
+	 * The handler decides for itself, because the answer depends on state the
+	 * router cannot see — whether this member opened *this* ticket, say.
+	 */
+	| { 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
+ * state can be appended after a colon (e.g. handler `role` claims `role:add:123`).
+ *
+ * Best practice — handler (this) vs collector ({@link import("@/discord/components/paginator").mountPaginator}):
+ * use a **handler** for *persistent* components that must keep working forever and
+ * survive a restart (role pickers, ticket/verify buttons); the bot has no
+ * in-memory closure after a restart, so encode state in the customId (or refetch
+ * it). Use a **collector** for *transient*, single-message, owner-scoped flows
+ * with a lifetime (pagination, a confirm dialog) — its state lives in memory and
+ * dies on idle.
+ */
+export interface ComponentHandler {
+	readonly customId: string;
+	/** Who may act on this component. Required: see {@link ComponentAuthorization}. */
+	readonly authorize: ComponentAuthorization;
+	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;
+}
+
+function isRoutable(interaction: Interaction): interaction is RoutableInteraction {
+	return interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit();
+}
+
+/**
+ * Routes persistent component/modal interactions to registered handlers by
+ * `customId`, injecting the shared {@link ComponentRuntime}. It does not attach
+ * its own listener — it is an {@link InteractionDispatcher} driven by the shared
+ * {@link import("@/discord/interaction/interaction-router").InteractionRouter},
+ * so commands and components share a single `interactionCreate` listener.
+ */
+export class ComponentRouter implements InteractionDispatcher {
+	private readonly handlers: ComponentHandler[] = [];
+	private readonly runtime: ComponentRuntime;
+
+	constructor(private readonly deps: ComponentRouterDeps) {
+		this.runtime = {
+			presenter: deps.presenter,
+			logger: deps.logger,
+			translator: deps.translator,
+		};
+	}
+
+	register(handler: ComponentHandler): this {
+		this.handlers.push(handler);
+		return this;
+	}
+
+	registerAll(handlers: Iterable<ComponentHandler>): this {
+		for (const handler of handlers) {
+			this.register(handler);
+		}
+		return this;
+	}
+
+	private match(customId: string): ComponentHandler | undefined {
+		return this.handlers.find(
+			(handler) => customId === handler.customId || customId.startsWith(`${handler.customId}:`),
+		);
+	}
+
+	/** Claim and route component/modal interactions by `customId`; ignore the rest. */
+	async handle(interaction: Interaction): Promise<boolean> {
+		if (!isRoutable(interaction)) {
+			return false;
+		}
+		const handler = this.match(interaction.customId);
+		if (!handler) {
+			return false;
+		}
+		// 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;
+		}
+		try {
+			await handler.handle(interaction, this.runtime);
+		} catch (error) {
+			this.deps.logger.error(
+				{
+					customId: interaction.customId,
+					err: error instanceof Error ? error.message : String(error),
+				},
+				"Component handler failed",
+			);
+		}
+		return true;
+	}
+
+	/**
+	 * Enforce the handler's declared audience. Only `permissions` is enforceable
+	 * here — the other two kinds are statements about a decision made elsewhere,
+	 * and their value is that the handler had to state one.
+	 *
+	 * `memberPermissions` is `null` outside a guild; that is a denial, since an
+	 * unknown permission set must never be read as a granted one — the same rule
+	 * `createPermissionGuard` follows for commands.
+	 */
+	private async passesAuthorization(
+		interaction: RoutableInteraction,
+		handler: ComponentHandler,
+	): Promise<boolean> {
+		if (handler.authorize.kind !== "permissions") {
+			return true;
+		}
+		const missing = missingPermissions(interaction.memberPermissions, handler.authorize.required);
+		if (missing.length === 0) {
+			return true;
+		}
+
+		const locale = this.localeOf(interaction);
+		const message = this.deps.translator.translate(locale, CORE_MESSAGES.guardPermissionDenied, {
+			missing: formatPermissions(missing),
+		});
+		await interaction.reply({
+			embeds: [this.deps.presenter.denial(message, locale)],
+			flags: MessageFlags.Ephemeral,
+		});
+		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

@@ -0,0 +1,18 @@
+export {
+	COLLECTOR_IDLE_MS,
+	createStateStore,
+	type DisabledInteractiveMessageComponents,
+	type InteractiveMessageCollectorDeps,
+	type InteractiveMessageHandle,
+	type InteractiveMessagePayload,
+	type InteractiveSelect,
+	type InteractiveView,
+	mountInteractiveMessageCollector,
+	type SelectComponentContext,
+	type StateStore,
+	toMessageEditOptions,
+} from "@/discord/components/interactive-message/interactive-message-collector";
+export {
+	type InteractiveMessageOptions,
+	mountInteractiveMessage,
+} from "@/discord/components/interactive-message/mount-interactive-message";