@azurioh/discord-kernel 0.1.0

package/src/discord/interaction/select-menu.ts

@@ -0,0 +1,246 @@
+import {
+	ActionRowBuilder,
+	type AnySelectMenuInteraction,
+	ChannelSelectMenuBuilder,
+	type ChannelSelectMenuInteraction,
+	type ChannelType,
+	RoleSelectMenuBuilder,
+	type RoleSelectMenuInteraction,
+	StringSelectMenuBuilder,
+	type StringSelectMenuInteraction,
+	UserSelectMenuBuilder,
+	type UserSelectMenuInteraction,
+} from "discord.js";
+import type {
+	ComponentAuthorization,
+	ComponentHandler,
+} from "@/discord/components/component-router";
+
+/** The builders this DSL can produce; the union an action row accepts. */
+export type AnySelectMenuBuilder =
+	| StringSelectMenuBuilder
+	| ChannelSelectMenuBuilder
+	| RoleSelectMenuBuilder
+	| UserSelectMenuBuilder;
+
+/**
+ * Context handed to `onSelect`, mirroring
+ * {@link import("@/discord/interaction/button").ComponentContext}: the
+ * triggering interaction plus the picked values, already unwrapped so a handler
+ * does not have to know where discord.js keeps them.
+ */
+export interface SelectContext<I extends AnySelectMenuInteraction> {
+	readonly interaction: I;
+	readonly values: readonly string[];
+}
+
+/**
+ * Presentation options shared by every select flavour. Split from the handler so
+ * the shared `applyBaseOptions` never sees `onSelect`: a callback is
+ * contravariant in its interaction type, so a common supertype for the
+ * *definitions* cannot exist.
+ */
+export interface SelectLayout {
+	id: string;
+	placeholder?: string;
+	minValues?: number;
+	maxValues?: number;
+	disabled?: boolean;
+}
+
+/** A select declaration: its layout plus the behaviour it carries. */
+export interface BaseSelectDef<I extends AnySelectMenuInteraction> extends SelectLayout {
+	onSelect?: (ctx: SelectContext<I>) => Promise<void> | void;
+}
+
+/**
+ * Compiled select menu: renders itself (`apply`) and owns its behaviour
+ * (`onSelect`), exactly like a compiled
+ * {@link import("@/discord/interaction/button").Button}. It lives in the
+ * interaction layer for the same reason — it carries behaviour, it is not a
+ * passive widget.
+ */
+export interface SelectMenu<B, I extends AnySelectMenuInteraction> {
+	readonly id: string;
+	readonly onSelect?: (ctx: SelectContext<I>) => Promise<void> | void;
+	apply(forceDisabled?: boolean): B;
+}
+
+export interface StringSelectOption {
+	label: string;
+	value: string;
+	description?: string;
+	emoji?: string;
+	default?: boolean;
+}
+
+export interface StringSelectDef extends BaseSelectDef<StringSelectMenuInteraction> {
+	options: readonly StringSelectOption[];
+}
+
+export interface ChannelSelectDef extends BaseSelectDef<ChannelSelectMenuInteraction> {
+	/** Restricts what the picker offers, e.g. text channels only. */
+	channelTypes?: readonly ChannelType[];
+	/**
+	 * What the picker opens already holding.
+	 *
+	 * A picker returns its whole selection, never a delta, so one that opens
+	 * empty over a setting that already has a value turns "change this" into
+	 * "type the list again" — and anything the administrator forgets to re-pick
+	 * is silently dropped.
+	 */
+	defaultChannelIds?: readonly string[];
+}
+
+export interface RoleSelectDef extends BaseSelectDef<RoleSelectMenuInteraction> {
+	/** What the picker opens already holding. See {@link ChannelSelectDef.defaultChannelIds}. */
+	defaultRoleIds?: readonly string[];
+}
+
+export interface UserSelectDef extends BaseSelectDef<UserSelectMenuInteraction> {
+	/** What the picker opens already holding. See {@link ChannelSelectDef.defaultChannelIds}. */
+	defaultUserIds?: readonly string[];
+}
+
+/** Apply the options every select flavour shares onto its builder. */
+function applyBaseOptions<B extends AnySelectMenuBuilder>(
+	builder: B,
+	def: SelectLayout,
+	forceDisabled: boolean,
+): B {
+	builder.setCustomId(def.id);
+	if (def.placeholder !== undefined) {
+		builder.setPlaceholder(def.placeholder);
+	}
+	if (def.minValues !== undefined) {
+		builder.setMinValues(def.minValues);
+	}
+	if (def.maxValues !== undefined) {
+		builder.setMaxValues(def.maxValues);
+	}
+	builder.setDisabled(forceDisabled || (def.disabled ?? false));
+	return builder;
+}
+
+/** A menu of caller-defined string values. */
+export function createStringSelect(
+	def: StringSelectDef,
+): SelectMenu<StringSelectMenuBuilder, StringSelectMenuInteraction> {
+	return {
+		id: def.id,
+		onSelect: def.onSelect,
+		apply(forceDisabled = false) {
+			const builder = applyBaseOptions(new StringSelectMenuBuilder(), def, forceDisabled);
+			return builder.addOptions(
+				...def.options.map((option) => ({
+					label: option.label,
+					value: option.value,
+					description: option.description,
+					emoji: option.emoji,
+					default: option.default,
+				})),
+			);
+		},
+	};
+}
+
+/** A menu populated by Discord with the guild's channels. */
+export function createChannelSelect(
+	def: ChannelSelectDef,
+): SelectMenu<ChannelSelectMenuBuilder, ChannelSelectMenuInteraction> {
+	return {
+		id: def.id,
+		onSelect: def.onSelect,
+		apply(forceDisabled = false) {
+			const builder = applyBaseOptions(new ChannelSelectMenuBuilder(), def, forceDisabled);
+			if (def.defaultChannelIds !== undefined && def.defaultChannelIds.length > 0) {
+				builder.setDefaultChannels(...def.defaultChannelIds);
+			}
+			if (def.channelTypes !== undefined) {
+				builder.setChannelTypes(...def.channelTypes);
+			}
+			return builder;
+		},
+	};
+}
+
+/** A menu populated by Discord with the guild's roles. */
+export function createRoleSelect(
+	def: RoleSelectDef,
+): SelectMenu<RoleSelectMenuBuilder, RoleSelectMenuInteraction> {
+	return {
+		id: def.id,
+		onSelect: def.onSelect,
+		apply(forceDisabled = false) {
+			const builder = applyBaseOptions(new RoleSelectMenuBuilder(), def, forceDisabled);
+			if (def.defaultRoleIds !== undefined && def.defaultRoleIds.length > 0) {
+				builder.setDefaultRoles(...def.defaultRoleIds);
+			}
+			return builder;
+		},
+	};
+}
+
+/**
+ * A menu populated by Discord with the guild's members.
+ *
+ * A distinct flavour from the mentionable one on purpose: naming a person is not
+ * the same act as naming a role, and the calls behind it — adding someone to the
+ * recap's ping list, granting a user a level — take a user id, not either.
+ */
+export function createUserSelect(
+	def: UserSelectDef,
+): SelectMenu<UserSelectMenuBuilder, UserSelectMenuInteraction> {
+	return {
+		id: def.id,
+		onSelect: def.onSelect,
+		apply(forceDisabled = false) {
+			const builder = applyBaseOptions(new UserSelectMenuBuilder(), def, forceDisabled);
+			if (def.defaultUserIds !== undefined && def.defaultUserIds.length > 0) {
+				builder.setDefaultUsers(...def.defaultUserIds);
+			}
+			return builder;
+		},
+	};
+}
+
+/**
+ * Wrap a select menu in its own action row. Unlike buttons, Discord gives a
+ * select menu a whole row, so there is nothing to group — hence a distinct
+ * helper from `createActionRow`.
+ */
+export function createSelectRow<B extends AnySelectMenuBuilder, I extends AnySelectMenuInteraction>(
+	menu: SelectMenu<B, I>,
+	forceDisabled = false,
+): ActionRowBuilder<B> {
+	return new ActionRowBuilder<B>().addComponents(menu.apply(forceDisabled));
+}
+
+/**
+ * Bridge a select menu's `onSelect` to the persistent
+ * {@link import("@/discord/components/component-router").ComponentRouter}.
+ *
+ * Without this a declared `onSelect` would never run: the router dispatches to a
+ * `ComponentHandler`, and nothing else turns an interaction back into the menu
+ * that produced it. Register the result through a module's `components`.
+ */
+export function createSelectHandler<
+	B extends AnySelectMenuBuilder,
+	I extends AnySelectMenuInteraction,
+>(menu: SelectMenu<B, I>, authorize: ComponentAuthorization): ComponentHandler {
+	return {
+		customId: menu.id,
+		// Passed in rather than defaulted: this bridge knows nothing about what
+		// the menu does, and a default here would be exactly the silent "anyone
+		// may click" the required field exists to prevent.
+		authorize,
+		async handle(interaction) {
+			// The router also routes buttons and modals to a matching customId; a
+			// menu only speaks for select interactions.
+			if (!interaction.isAnySelectMenu()) {
+				return;
+			}
+			await menu.onSelect?.({ interaction: interaction as I, values: interaction.values });
+		},
+	};
+}

package/src/discord/permissions.ts

@@ -0,0 +1,57 @@
+import { PermissionFlagsBits, PermissionsBitField } from "discord.js";
+
+/**
+ * Permission helpers shared by the command DSL, the guards and any adapter that
+ * needs to reason about what the bot (or a member) is allowed to do.
+ *
+ * Everything is expressed in terms of {@link PermissionBit} rather than raw
+ * `bigint`s: the values come from discord.js' `PermissionFlagsBits`, so a typo
+ * is a type error instead of a silently wrong bitfield.
+ */
+
+/**
+ * A single Discord permission flag. Deriving the type from the enum-like object
+ * means the DSL accepts `PermissionFlagsBits.ManageChannels` and rejects an
+ * arbitrary `bigint`.
+ */
+export type PermissionBit = (typeof PermissionFlagsBits)[keyof typeof PermissionFlagsBits];
+
+/** Combine permission flags into the single bitfield Discord's API expects. */
+export function resolvePermissions(permissions: readonly PermissionBit[]): bigint {
+	return PermissionsBitField.resolve([...permissions]);
+}
+
+/**
+ * Bits in `required` that `held` lacks (empty when everything is granted).
+ *
+ * `held === null` means the permissions could not be resolved (outside a guild,
+ * or an uncached member). It returns *all* of `required`: an absent answer must
+ * never be mistaken for a granted one.
+ */
+export function missingPermissions(
+	held: Readonly<PermissionsBitField> | null,
+	required: readonly PermissionBit[],
+): PermissionBit[] {
+	if (held === null) {
+		return [...required];
+	}
+	return required.filter((permission) => !held.has(permission));
+}
+
+/**
+ * Human-readable names for permission bits, for user-facing messages. Resolved
+ * by reverse lookup in `PermissionFlagsBits` so the names track discord.js
+ * rather than a hand-maintained table that silently rots.
+ */
+export function formatPermissions(permissions: readonly PermissionBit[]): string {
+	return permissions.map(permissionName).join(", ");
+}
+
+function permissionName(permission: PermissionBit): string {
+	for (const [name, bit] of Object.entries(PermissionFlagsBits)) {
+		if (bit === permission) {
+			return name;
+		}
+	}
+	return String(permission);
+}

package/src/discord/placeholder-registry-errors.ts

@@ -0,0 +1,11 @@
+/**
+ * Two providers registered the same token. Raised while modules register their
+ * placeholders at boot — a wiring mistake that must stop the boot, never a
+ * runtime condition a guild's rendered text could trigger.
+ */
+export class DuplicatePlaceholderTokenError extends Error {
+	constructor(readonly token: string) {
+		super(`Placeholder token "${token}" is registered twice`);
+		this.name = "DuplicatePlaceholderTokenError";
+	}
+}

package/src/discord/placeholder-registry.ts

@@ -0,0 +1,77 @@
+import { DuplicatePlaceholderTokenError } from "@/discord/placeholder-registry-errors";
+import type { Locale } from "@/i18n";
+
+/**
+ * A token a module offers to text another module's administrator writes,
+ * resolved only once that text is actually rendered.
+ *
+ * `core` sits between the two by design: a module that publishes a token
+ * (`tournament`'s `{tournament_template}`) and a module that renders text
+ * carrying it (`ticket`'s welcome message) never import each other —
+ * `AGENTS.md` forbids it. Both go through {@link PlaceholderRegistry} instead,
+ * which `bootstrap` hands to every module factory from the same container-held
+ * instance, so neither module ever names the other.
+ */
+export interface PlaceholderProvider {
+	/** The token, braces included — `{tournament_template}`. */
+	readonly token: string;
+	/** What it becomes, for one guild, at render time. */
+	resolve(guildId: string, locale: Locale): Promise<string>;
+	/**
+	 * Catalog key describing this token in the legend an admin reads while
+	 * writing the text — owned by the module that offers the token, since it is
+	 * the only one that knows what the token means.
+	 */
+	readonly legendKey: string;
+}
+
+/**
+ * Accumulates every {@link PlaceholderProvider} registered at boot and resolves
+ * them against a piece of already-rendered text.
+ *
+ * Consulted at render, never at construction — that is what makes the order
+ * `bootstrap/modules.ts` lists modules in irrelevant here: a module registers
+ * into this from its own factory, whatever position it holds in that list, and
+ * `resolve` only ever reads the registry as it stands by the time some guild's
+ * text is actually rendered — well after every module has finished
+ * registering, unlike `ChannelExporter` (`bootstrap/channel-exporter.ts`),
+ * which has to be built with the enabled module list already known.
+ */
+export class PlaceholderRegistry {
+	private readonly providers: PlaceholderProvider[] = [];
+
+	/** @throws DuplicatePlaceholderTokenError — a boot-time wiring mistake. */
+	register(provider: PlaceholderProvider): void {
+		if (this.providers.some((existing) => existing.token === provider.token)) {
+			throw new DuplicatePlaceholderTokenError(provider.token);
+		}
+		this.providers.push(provider);
+	}
+
+	/** Every registered provider, in registration order — for building a legend. */
+	list(): readonly PlaceholderProvider[] {
+		return this.providers;
+	}
+
+	/** The token every registered provider answers to. */
+	tokens(): readonly string[] {
+		return this.providers.map((provider) => provider.token);
+	}
+
+	/**
+	 * Replace every registered token `text` carries with what it resolves to for
+	 * `guildId`/`locale`. A provider whose token is absent from `text` is never
+	 * asked to resolve — the common case, since one guild's text rarely uses
+	 * every token every module has ever registered.
+	 */
+	async resolve(text: string, guildId: string, locale: Locale): Promise<string> {
+		let result = text;
+		for (const provider of this.providers) {
+			if (result.includes(provider.token)) {
+				const value = await provider.resolve(guildId, locale);
+				result = result.split(provider.token).join(value);
+			}
+		}
+		return result;
+	}
+}

package/src/discord/presenter.ts

@@ -0,0 +1,26 @@
+import type { EmbedBuilder } from "discord.js";
+import type { Locale } from "@/i18n";
+
+/**
+ * Port that renders framework-level responses (errors, denials, confirmations)
+ * as embeds. The command pipeline depends on this interface, never on a concrete
+ * embed module — so a bot can fully restyle/localise feedback by providing its
+ * own implementation, with zero changes to the core.
+ *
+ * Every method receives the locale resolved for the interaction being answered,
+ * so titles and fixed copy follow the user's language, not the process's.
+ *
+ * The default implementation lives in `infrastructure/discord/default-presenter.ts`.
+ */
+export interface Presenter {
+	/** A successful, affirmative action. */
+	confirmation(message: string, locale: Locale): EmbedBuilder;
+	/** A benign business problem (bad input, missing resource, conflict). */
+	warning(message: string, locale: Locale): EmbedBuilder;
+	/** A serious—but expected—business error. */
+	error(message: string, locale: Locale): EmbedBuilder;
+	/** An authorization denial from a guard. */
+	denial(message: string, locale: Locale): EmbedBuilder;
+	/** An unexpected failure, carrying a quotable incident reference. */
+	systemError(message: string, reference: string, locale: Locale): EmbedBuilder;
+}