@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/discord/events/event-router.ts

@@ -1,20 +1,37 @@
 import type { Client } from "discord.js";
+import { eventGuildId } from "@/discord/events/event-guild-id";
 import type { DiscordEvent, EventListener } from "@/discord/events/types";
+import { isModuleDisabled } from "@/discord/settings/is-module-disabled";
+import { errorMessage } from "@/errors/error-message";
 import type { Logger } from "@/logger";
+import type { ModuleGate } from "@/settings/system/module-gate";
+
+/** A registered event and the module it belongs to, if any. */
+interface RegisteredEvent {
+	readonly event: DiscordEvent;
+	readonly moduleName: string | undefined;
+}
 
 /**
  * Wrap a handler so a thrown error is logged instead of escaping to the
  * process-level `error` event: a failing handler must never take the bot down.
+ * A handler of a module disabled on the event's guild is skipped silently.
  */
-function createEventListener(event: DiscordEvent, logger: Logger): EventListener {
+function createEventListener(params: {
+	registered: RegisteredEvent;
+	logger: Logger;
+	gate: ModuleGate | undefined;
+}): EventListener {
+	const { registered, logger, gate } = params;
+	const { event, moduleName } = registered;
 	return async (...args) => {
 		try {
+			if (await isModuleDisabled({ gate, moduleName, guildId: eventGuildId(args) })) {
+				return;
+			}
 			await event.execute(...args);
 		} catch (error) {
-			logger.error(
-				{ event: event.name, err: error instanceof Error ? error.message : String(error) },
-				"Event handler failed",
-			);
+			logger.error({ event: event.name, err: errorMessage(error) }, "Event handler failed");
 		}
 	};
 }
@@ -24,25 +41,41 @@ function createEventListener(event: DiscordEvent, logger: Logger): EventListener
  * the app that calls `client.on`/`client.once`.
  */
 export class EventRouter {
-	private readonly events: DiscordEvent[] = [];
+	private readonly events: RegisteredEvent[] = [];
 
-	constructor(private readonly logger: Logger) {}
+	/**
+	 * @param logger - where a failing handler is reported.
+	 * @param gate - when given, a handler registered with a module is skipped,
+	 * silently, for a guild where that module is disabled (FR-036). Events bound
+	 * to no guild always run.
+	 */
+	constructor(
+		private readonly logger: Logger,
+		private readonly gate?: ModuleGate,
+	) {}
 
-	register(event: DiscordEvent): this {
-		this.events.push(event);
+	/**
+	 * @param moduleName - the module the handler belongs to, so the gate can
+	 * skip it for guilds where that module is disabled. Omit it for a handler
+	 * that always runs.
+	 */
+	register(event: DiscordEvent, moduleName?: string): this {
+		this.events.push({ event, moduleName });
 		return this;
 	}
 
-	registerAll(events: Iterable<DiscordEvent>): this {
+	/** Register many handlers at once, all of `moduleName` when given. */
+	registerAll(events: Iterable<DiscordEvent>, moduleName?: string): this {
 		for (const event of events) {
-			this.register(event);
+			this.register(event, moduleName);
 		}
 		return this;
 	}
 
 	bind(client: Client): void {
-		for (const event of this.events) {
-			const listener = createEventListener(event, this.logger);
+		for (const registered of this.events) {
+			const { event } = registered;
+			const listener = createEventListener({ registered, logger: this.logger, gate: this.gate });
 			if (event.once) {
 				client.once(event.name, listener);
 			} else {

package/src/discord/i18n.ts

@@ -1,4 +1,4 @@
-import type { Catalog } from "@/i18n";
+import type { KeyedCatalog, MessageKey } from "@/i18n/catalog";
 
 /** Catalog keys for the framework's own feedback, under the `core.` namespace. */
 export const CORE_MESSAGES = {
@@ -50,6 +50,21 @@ export const SETTINGS_EDITOR_MESSAGES = {
 	 */
 	editFieldButton: "core.settings-editor.edit-field-button",
 	openLevelButton: "core.settings-editor.open-level-button",
+	/** The line under an entry whose declaration describes it no further. */
+	entryHint: "core.settings-editor.entry-hint",
+	/** A card entry's current value, under its hint. Takes `{value}`. */
+	currentValue: "core.settings-editor.current-value",
+	/** The entry a screen with more entries than one card holds moves the rest behind. */
+	moreEntries: "core.settings-editor.more-entries",
+	moreEntriesHint: "core.settings-editor.more-entries-hint",
+	/**
+	 * An option whose text is not a catalog key: a search result, already in
+	 * the reader's language. Takes `{label}` and shows it as is.
+	 */
+	choiceLabel: "core.settings-editor.choice-label",
+	/** The free entry beside a searchable setting's list, for a value the list does not offer. */
+	otherValue: "core.settings-editor.other-value",
+	otherValueHelper: "core.settings-editor.other-value-helper",
 } as const;
 
 /**
@@ -57,7 +72,9 @@ export const SETTINGS_EDITOR_MESSAGES = {
  * fallbacks and the default cooldown notice. Registered by the composition root
  * before any module catalog.
  */
-export const CORE_CATALOG: Catalog = {
+export const CORE_CATALOG: KeyedCatalog<
+	MessageKey<typeof CORE_MESSAGES> | MessageKey<typeof SETTINGS_EDITOR_MESSAGES>
+> = {
 	[CORE_MESSAGES.presenterSuccessTitle]: { en: "Success", fr: "Succès" },
 	[CORE_MESSAGES.presenterWarningTitle]: { en: "Warning", fr: "Avertissement" },
 	[CORE_MESSAGES.presenterErrorTitle]: { en: "Error", fr: "Erreur" },
@@ -96,7 +113,7 @@ export const CORE_CATALOG: Catalog = {
 	},
 	[SETTINGS_EDITOR_MESSAGES.modalHelper]: {
 		en: "Leave empty to clear your customisation and go back to the default.",
-		fr: "Laisse vide pour effacer ta personnalisation et revenir à la valeur par défaut.",
+		fr: "Laissez vide pour effacer votre personnalisation et revenir à la valeur par défaut.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.modalUploadLabel]: {
 		en: "Upload an image",
@@ -112,11 +129,11 @@ export const CORE_CATALOG: Catalog = {
 	},
 	[SETTINGS_EDITOR_MESSAGES.modalImageHelper]: {
 		en: "An http(s) address. Leave both empty to restore the default.",
-		fr: "Une adresse http(s). Laisse les deux vides pour revenir au défaut.",
+		fr: "Une adresse http(s). Laissez les deux vides pour revenir au défaut.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.modalImageHelperUploaded]: {
 		en: "An image is uploaded; it cannot be shown here. Empty both to restore the default.",
-		fr: "Une image est envoyée ; impossible de la réafficher. Vide les deux pour le défaut.",
+		fr: "Une image est envoyée ; impossible de la réafficher. Videz les deux pour le défaut.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.fieldSaved]: {
 		en: "✅ {field} updated.",
@@ -128,7 +145,7 @@ export const CORE_CATALOG: Catalog = {
 	},
 	[SETTINGS_EDITOR_MESSAGES.fieldUploaded]: {
 		en: "✅ {field} updated with your upload.",
-		fr: "✅ {field} mis à jour avec ton envoi.",
+		fr: "✅ {field} mis à jour avec votre envoi.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.resetButton]: {
 		en: "Reset everything",
@@ -140,7 +157,7 @@ export const CORE_CATALOG: Catalog = {
 	},
 	[SETTINGS_EDITOR_MESSAGES.resetConfirmDescription]: {
 		en: "Every field goes back to its default. An uploaded image is not merely unset — its file is deleted for good and cannot be recovered. The preview below is what you are about to lose.",
-		fr: "Chaque champ revient à sa valeur par défaut. Une image envoyée n'est pas simplement retirée : le fichier est supprimé définitivement et ne pourra pas être récupéré. L'aperçu ci-dessous est ce que tu es sur le point de perdre.",
+		fr: "Chaque champ revient à sa valeur par défaut. Une image envoyée n'est pas simplement retirée : le fichier est supprimé définitivement et ne pourra pas être récupéré. L'aperçu ci-dessous est ce que vous êtes sur le point de perdre.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.resetConfirmButton]: {
 		en: "Reset for good",
@@ -156,7 +173,7 @@ export const CORE_CATALOG: Catalog = {
 	},
 	[SETTINGS_EDITOR_MESSAGES.resetCancelled]: {
 		en: "Nothing was reset. Your customisation is untouched.",
-		fr: "Rien n'a été réinitialisé. Ta personnalisation est intacte.",
+		fr: "Rien n'a été réinitialisé. Votre personnalisation est intacte.",
 	},
 	[SETTINGS_EDITOR_MESSAGES.backButton]: {
 		en: "Back",
@@ -170,4 +187,26 @@ export const CORE_CATALOG: Catalog = {
 		en: "Open",
 		fr: "Ouvrir",
 	},
+	[SETTINGS_EDITOR_MESSAGES.entryHint]: {
+		en: "Edit this setting.",
+		fr: "Modifiez ce paramètre.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.currentValue]: {
+		en: "Current: {value}",
+		fr: "Actuel : {value}",
+	},
+	[SETTINGS_EDITOR_MESSAGES.moreEntries]: {
+		en: "More settings",
+		fr: "Plus de paramètres",
+	},
+	[SETTINGS_EDITOR_MESSAGES.moreEntriesHint]: {
+		en: "The settings that do not fit on this page.",
+		fr: "Les paramètres qui ne tiennent pas sur cette page.",
+	},
+	[SETTINGS_EDITOR_MESSAGES.choiceLabel]: { en: "{label}", fr: "{label}" },
+	[SETTINGS_EDITOR_MESSAGES.otherValue]: { en: "Other value", fr: "Autre valeur" },
+	[SETTINGS_EDITOR_MESSAGES.otherValueHelper]: {
+		en: "A value the list above does not offer; it replaces the pick. Leave empty to keep the pick.",
+		fr: "Une valeur absente de la liste ci-dessus ; elle remplace le choix. Laissez vide pour garder le choix.",
+	},
 };

package/src/discord/interaction/interaction-locale.ts

@@ -0,0 +1,19 @@
+import { type Locale, resolveLocale } from "@/i18n/locale";
+import type { Translator } from "@/i18n/translator";
+
+/** The two locales Discord attaches to every interaction. */
+interface LocalizedInteraction {
+	readonly locale: string;
+	readonly guildLocale: string | null;
+}
+
+/**
+ * The reply language for one interaction: the member's client locale, then the
+ * guild's, then the translator's configured default.
+ */
+export function interactionLocale(
+	interaction: LocalizedInteraction,
+	translator: Translator,
+): Locale {
+	return resolveLocale([interaction.locale, interaction.guildLocale], translator.defaultLocale);
+}

package/src/discord/interaction/locale-resolver.ts

@@ -0,0 +1,28 @@
+import type { Locale } from "@/i18n/locale";
+
+/**
+ * What a {@link LocaleResolver} knows of the interaction it answers: the
+ * member's client locale, and the guild's id and Discord locale (`null` outside
+ * a guild). Every discord.js interaction fits as is.
+ */
+export interface LocaleSubject {
+	readonly locale: string;
+	readonly guildLocale: string | null;
+	readonly guildId: string | null;
+}
+
+/**
+ * The port the kernel reads the reply language through, on every path that
+ * answers an interaction (commands, guards, failures, components). The bot
+ * picks the implementation at composition: `createGuildLocaleResolver` for the
+ * guild's language setting (FR-038), or its own. Without one, the kernel uses
+ * the interaction's own locales (`interactionLocale`).
+ */
+export interface LocaleResolver {
+	/**
+	 * @returns the language to reply in.
+	 * @throws whatever the implementation's lookup throws; the kernel logs it
+	 * and falls back to the interaction's own locales.
+	 */
+	resolve(subject: LocaleSubject): Promise<Locale>;
+}

package/src/discord/interaction/modal.ts

@@ -14,6 +14,7 @@ import {
 	TextInputStyle,
 	UserSelectMenuBuilder,
 } from "discord.js";
+import { applySelectBounds } from "@/discord/interaction/select-bounds";
 
 export type TextFieldStyleName = "short" | "paragraph";
 
@@ -264,16 +265,7 @@ function createStringSelect(name: string, field: SelectFieldDef): StringSelectMe
 		.setCustomId(name)
 		.setRequired(field.required ?? true)
 		.addOptions(field.options.map(createSelectOption));
-	if (field.placeholder !== undefined) {
-		select.setPlaceholder(field.placeholder);
-	}
-	if (field.minValues !== undefined) {
-		select.setMinValues(field.minValues);
-	}
-	if (field.maxValues !== undefined) {
-		select.setMaxValues(field.maxValues);
-	}
-	return select;
+	return applySelectBounds(select, field);
 }
 
 function createRoleSelect(name: string, field: RoleFieldDef): RoleSelectMenuBuilder {
@@ -281,16 +273,7 @@ function createRoleSelect(name: string, field: RoleFieldDef): RoleSelectMenuBuil
 	if (field.defaultRoleIds !== undefined) {
 		select.setDefaultRoles(...field.defaultRoleIds);
 	}
-	if (field.placeholder !== undefined) {
-		select.setPlaceholder(field.placeholder);
-	}
-	if (field.minValues !== undefined) {
-		select.setMinValues(field.minValues);
-	}
-	if (field.maxValues !== undefined) {
-		select.setMaxValues(field.maxValues);
-	}
-	return select;
+	return applySelectBounds(select, field);
 }
 
 function createUserSelect(name: string, field: UserFieldDef): UserSelectMenuBuilder {
@@ -298,16 +281,7 @@ function createUserSelect(name: string, field: UserFieldDef): UserSelectMenuBuil
 	if (field.defaultUserIds !== undefined) {
 		select.setDefaultUsers(...field.defaultUserIds);
 	}
-	if (field.placeholder !== undefined) {
-		select.setPlaceholder(field.placeholder);
-	}
-	if (field.minValues !== undefined) {
-		select.setMinValues(field.minValues);
-	}
-	if (field.maxValues !== undefined) {
-		select.setMaxValues(field.maxValues);
-	}
-	return select;
+	return applySelectBounds(select, field);
 }
 
 function createChannelSelect(name: string, field: ChannelFieldDef): ChannelSelectMenuBuilder {
@@ -320,16 +294,7 @@ function createChannelSelect(name: string, field: ChannelFieldDef): ChannelSelec
 	if (field.defaultChannelIds !== undefined) {
 		select.setDefaultChannels(...field.defaultChannelIds);
 	}
-	if (field.placeholder !== undefined) {
-		select.setPlaceholder(field.placeholder);
-	}
-	if (field.minValues !== undefined) {
-		select.setMinValues(field.minValues);
-	}
-	if (field.maxValues !== undefined) {
-		select.setMaxValues(field.maxValues);
-	}
-	return select;
+	return applySelectBounds(select, field);
 }
 
 function createLabel(name: string, field: FieldDef): LabelBuilder {

package/src/discord/interaction/reply-locale.ts

@@ -0,0 +1,35 @@
+import { interactionLocale } from "@/discord/interaction/interaction-locale";
+import type { LocaleResolver, LocaleSubject } from "@/discord/interaction/locale-resolver";
+import { errorMessage } from "@/errors/error-message";
+import type { Locale } from "@/i18n/locale";
+import type { Translator } from "@/i18n/translator";
+import type { Logger } from "@/logger";
+
+/** The dependencies every reply path already carries, plus the bot's optional resolver. */
+export interface ReplyLocaleDeps {
+	readonly translator: Translator;
+	readonly logger: Logger;
+	readonly localeResolver?: LocaleResolver;
+}
+
+/**
+ * The language the kernel answers an interaction in: the bot's
+ * {@link LocaleResolver} when it gave one, otherwise the interaction's own
+ * locales. A resolver that fails is logged and the interaction's own locales
+ * are used, so a store outage never leaves a member without an answer.
+ */
+export async function replyLocale(subject: LocaleSubject, deps: ReplyLocaleDeps): Promise<Locale> {
+	const { translator, logger, localeResolver } = deps;
+	if (localeResolver === undefined) {
+		return interactionLocale(subject, translator);
+	}
+	try {
+		return await localeResolver.resolve(subject);
+	} catch (error) {
+		logger.error(
+			{ guildId: subject.guildId, err: errorMessage(error) },
+			"Could not resolve the reply language; using the interaction's locales",
+		);
+		return interactionLocale(subject, translator);
+	}
+}

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

@@ -0,0 +1,33 @@
+/**
+ * What every select menu may declare, whatever it picks from and wherever it
+ * is shown (a message or a modal): its hint and how many picks it takes.
+ */
+export interface SelectBounds {
+	placeholder?: string;
+	minValues?: number;
+	maxValues?: number;
+}
+
+/** The setters every discord.js select menu builder carries for {@link SelectBounds}. */
+interface SelectBoundsBuilder {
+	setPlaceholder(placeholder: string): unknown;
+	setMinValues(minValues: number): unknown;
+	setMaxValues(maxValues: number): unknown;
+}
+
+/** Apply the placeholder and pick-count bounds a select declared, leaving unset ones to Discord. */
+export function applySelectBounds<B extends SelectBoundsBuilder>(
+	builder: B,
+	bounds: SelectBounds,
+): B {
+	if (bounds.placeholder !== undefined) {
+		builder.setPlaceholder(bounds.placeholder);
+	}
+	if (bounds.minValues !== undefined) {
+		builder.setMinValues(bounds.minValues);
+	}
+	if (bounds.maxValues !== undefined) {
+		builder.setMaxValues(bounds.maxValues);
+	}
+	return builder;
+}

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

@@ -15,6 +15,7 @@ import type {
 	ComponentAuthorization,
 	ComponentHandler,
 } from "@/discord/components/component-router";
+import { applySelectBounds } from "@/discord/interaction/select-bounds";
 
 /** The builders this DSL can produce; the union an action row accepts. */
 export type AnySelectMenuBuilder =
@@ -109,15 +110,7 @@ function applyBaseOptions<B extends AnySelectMenuBuilder>(
 	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);
-	}
+	applySelectBounds(builder, def);
 	builder.setDisabled(forceDisabled || (def.disabled ?? false));
 	return builder;
 }

package/src/discord/placeholder-registry.ts

@@ -1,5 +1,5 @@
 import { DuplicatePlaceholderTokenError } from "@/discord/placeholder-registry-errors";
-import type { Locale } from "@/i18n";
+import type { Locale } from "@/i18n/locale";
 
 /**
  * A token a module offers to text another module's administrator writes,

package/src/discord/presenter.ts

@@ -1,5 +1,5 @@
 import type { EmbedBuilder } from "discord.js";
-import type { Locale } from "@/i18n";
+import type { Locale } from "@/i18n/locale";
 
 /**
  * Port that renders framework-level responses (errors, denials, confirmations)

package/src/discord/settings/discord-guild-directory.ts

@@ -0,0 +1,214 @@
+import { ChannelType, type Client, type Guild } from "discord.js";
+import { isMissingAccess, isUnknownResource } from "@/discord/api-errors";
+import { MAX_AUTOCOMPLETE_CHOICES } from "@/discord/command/autocomplete-limits";
+import type { ChannelKind, GuildDirectory } from "@/settings/ports/guild-directory";
+
+/** Every `ChannelType` a guild channel can have: all of them except the DM ones. */
+type GuildChannelType = Exclude<ChannelType, ChannelType.DM | ChannelType.GroupDM>;
+
+/**
+ * Discord's guild channel types to the kernel's kinds. Both maps are checked
+ * for completeness, so a new member on either side is a compile error until
+ * it is mapped here.
+ */
+const KIND_BY_CHANNEL_TYPE = {
+	[ChannelType.GuildText]: "text",
+	[ChannelType.GuildVoice]: "voice",
+	[ChannelType.GuildCategory]: "category",
+	[ChannelType.GuildAnnouncement]: "announcement",
+	[ChannelType.AnnouncementThread]: "announcementThread",
+	[ChannelType.PublicThread]: "publicThread",
+	[ChannelType.PrivateThread]: "privateThread",
+	[ChannelType.GuildStageVoice]: "stage",
+	[ChannelType.GuildDirectory]: "directory",
+	[ChannelType.GuildForum]: "forum",
+	[ChannelType.GuildMedia]: "media",
+} as const satisfies Record<GuildChannelType, ChannelKind>;
+
+/** The kernel's channel kinds to Discord's guild channel types: the inverse of the map above. */
+export const CHANNEL_TYPE_BY_KIND = {
+	text: ChannelType.GuildText,
+	voice: ChannelType.GuildVoice,
+	category: ChannelType.GuildCategory,
+	announcement: ChannelType.GuildAnnouncement,
+	announcementThread: ChannelType.AnnouncementThread,
+	publicThread: ChannelType.PublicThread,
+	privateThread: ChannelType.PrivateThread,
+	stage: ChannelType.GuildStageVoice,
+	directory: ChannelType.GuildDirectory,
+	forum: ChannelType.GuildForum,
+	media: ChannelType.GuildMedia,
+} as const satisfies Record<ChannelKind, GuildChannelType>;
+
+/** Discord caps autocomplete at this many choices, so no search returns more. */
+const SEARCH_LIMIT = MAX_AUTOCOMPLETE_CHOICES;
+
+interface NamedEntity {
+	readonly id: string;
+	readonly name: string;
+}
+
+interface ChannelEntity extends NamedEntity {
+	readonly kind: ChannelKind;
+}
+
+/** The minimal shape of a guild channel this adapter reads. */
+interface GuildChannelLike {
+	readonly id: string;
+	readonly name: string;
+	readonly type: GuildChannelType;
+}
+
+/** The minimal shape of a guild member this adapter reads. */
+interface GuildMemberLike {
+	readonly id: string;
+	readonly displayName: string;
+}
+
+/** Resolve to `null` when Discord says the entity does not exist; rethrow anything else. */
+async function orNullWhenUnknown<T>(lookup: Promise<T | null>): Promise<T | null> {
+	try {
+		return await lookup;
+	} catch (error) {
+		if (isUnknownResource(error)) {
+			return null;
+		}
+		throw error;
+	}
+}
+
+function toChannel(channel: GuildChannelLike): ChannelEntity {
+	return { id: channel.id, name: channel.name, kind: KIND_BY_CHANNEL_TYPE[channel.type] };
+}
+
+function toMember(member: GuildMemberLike): NamedEntity {
+	return { id: member.id, name: member.displayName };
+}
+
+function nameStartsWith(params: { name: string; query: string }): boolean {
+	return params.name.toLowerCase().startsWith(params.query.toLowerCase());
+}
+
+/**
+ * Search `cached` first; only when nothing there matches, search what `fetch`
+ * returns. discord.js caches what it fetches, so the next lookup is local.
+ */
+async function searchCacheThenFetch<T>(params: {
+	cached: Iterable<T>;
+	fetch: () => Promise<Iterable<T>>;
+	matches: (entity: T) => boolean;
+}): Promise<T[]> {
+	const { cached, fetch, matches } = params;
+	const hits = [...cached].filter(matches);
+	if (hits.length > 0) {
+		return hits.slice(0, SEARCH_LIMIT);
+	}
+	return [...(await fetch())].filter(matches).slice(0, SEARCH_LIMIT);
+}
+
+/** The guild from the client's cache, else from Discord; `null` when the bot cannot see it. */
+async function findGuild(params: { client: Client; guildId: string }): Promise<Guild | null> {
+	const { client, guildId } = params;
+	const cached = client.guilds.cache.get(guildId);
+	if (cached) {
+		return cached;
+	}
+	try {
+		return await client.guilds.fetch(guildId);
+	} catch (error) {
+		if (isUnknownResource(error) || isMissingAccess(error)) {
+			return null;
+		}
+		throw error;
+	}
+}
+
+/**
+ * {@link GuildDirectory} over a discord.js client. Every lookup reads the
+ * client's cache first and asks Discord only on a miss; an entity Discord does
+ * not know, or a guild the bot is not in, reads as absent. Search matches a
+ * case-insensitive name prefix, except the member search Discord runs itself
+ * on a cache miss, and returns at most 25 entries.
+ *
+ * @param client - the bot's client; its caches are read, never filled by hand.
+ * @returns the directory the settings service validates references with.
+ */
+export function createDiscordGuildDirectory(client: Client): GuildDirectory {
+	return {
+		async channel(guildId, id) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return null;
+			}
+			const channel =
+				guild.channels.cache.get(id) ?? (await orNullWhenUnknown(guild.channels.fetch(id)));
+			return channel ? toChannel(channel) : null;
+		},
+
+		async role(guildId, id) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return null;
+			}
+			const role = guild.roles.cache.get(id) ?? (await orNullWhenUnknown(guild.roles.fetch(id)));
+			return role ? { id: role.id, name: role.name } : null;
+		},
+
+		async member(guildId, id) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return null;
+			}
+			const member =
+				guild.members.cache.get(id) ?? (await orNullWhenUnknown(guild.members.fetch(id)));
+			return member ? toMember(member) : null;
+		},
+
+		async searchChannels(guildId, query, kinds) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return [];
+			}
+			const types = kinds?.map((kind): GuildChannelType => CHANNEL_TYPE_BY_KIND[kind]);
+			const channels = await searchCacheThenFetch<GuildChannelLike>({
+				cached: guild.channels.cache.values(),
+				fetch: async () => {
+					const fetched = await guild.channels.fetch();
+					return [...fetched.values()].filter((channel) => channel !== null);
+				},
+				matches: (channel) =>
+					nameStartsWith({ name: channel.name, query }) &&
+					(types === undefined || types.includes(channel.type)),
+			});
+			return channels.map(toChannel);
+		},
+
+		async searchRoles(guildId, query) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return [];
+			}
+			const roles = await searchCacheThenFetch({
+				cached: guild.roles.cache.values(),
+				fetch: async () => (await guild.roles.fetch()).values(),
+				matches: (role) => nameStartsWith({ name: role.name, query }),
+			});
+			return roles.map((role) => ({ id: role.id, name: role.name }));
+		},
+
+		async searchMembers(guildId, query) {
+			const guild = await findGuild({ client, guildId });
+			if (!guild) {
+				return [];
+			}
+			const hits = [...guild.members.cache.values()].filter((member) =>
+				nameStartsWith({ name: member.displayName, query }),
+			);
+			if (hits.length > 0) {
+				return hits.slice(0, SEARCH_LIMIT).map(toMember);
+			}
+			const found = await guild.members.search({ query, limit: SEARCH_LIMIT });
+			return [...found.values()].map(toMember);
+		},
+	};
+}