@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/settings/messages.ts

@@ -0,0 +1,161 @@
+import type { KeyedCatalog, MessageKey } from "@/i18n/catalog";
+import type { SettingsIssueCode } from "@/settings/settings-validation-error";
+
+/**
+ * Catalog key of each validation issue. Typed over every {@link SettingsIssueCode}
+ * so adding a code without its wording fails to compile.
+ *
+ * Placeholders: `min` / `minLength` / `minItems` take `{min}`, `max` /
+ * `maxLength` / `maxItems` take `{max}`; the others take none.
+ */
+export const SETTINGS_ISSUE_MESSAGES = {
+	required: "core.settings.issue.required",
+	type: "core.settings.issue.type",
+	min: "core.settings.issue.min",
+	max: "core.settings.issue.max",
+	minLength: "core.settings.issue.min-length",
+	maxLength: "core.settings.issue.max-length",
+	minItems: "core.settings.issue.min-items",
+	maxItems: "core.settings.issue.max-items",
+	duplicate: "core.settings.issue.duplicate",
+	channelType: "core.settings.issue.channel-type",
+	notFound: "core.settings.issue.not-found",
+	unknownChoice: "core.settings.issue.unknown-choice",
+	unknownField: "core.settings.issue.unknown-field",
+} as const satisfies Readonly<Record<SettingsIssueCode, string>>;
+
+/** Catalog keys for the settings feature's own wording outside validation. */
+export const SETTINGS_MESSAGES = {
+	/** Shown instead of a secret's value, which no surface ever reads back. */
+	secretSet: "core.settings.secret.set",
+	secretNotSet: "core.settings.secret.not-set",
+	/** Shown for a stored channel, role or member the guild no longer has. */
+	valueUnavailable: "core.settings.value.unavailable",
+	/** Shown for a setting that holds no value. */
+	valueNotSet: "core.settings.value.not-set",
+	/** Shown for a toggles setting with none of its toggles on. */
+	valueNone: "core.settings.value.none",
+	/** The two options a yes/no setting is picked from. */
+	booleanTrue: "core.settings.boolean.true",
+	booleanFalse: "core.settings.boolean.false",
+	/** Reply when a module disabled on the guild is used there. */
+	moduleDisabled: "core.settings.module.disabled",
+	/** Reply when a module still lacks a required setting. */
+	moduleNotConfigured: "core.settings.module.not-configured",
+	/** The missing settings, listed only to members who can fix them. */
+	moduleNotConfiguredMissing: "core.settings.module.not-configured-missing",
+} as const;
+
+/** Catalog keys of the kernel's own settings declaration (`kernelSettings`). */
+export const KERNEL_SETTINGS_MESSAGES = {
+	title: "core.settings.kernel.title",
+	description: "core.settings.kernel.description",
+	modules: "core.settings.kernel.modules",
+	modulesDescription: "core.settings.kernel.modules-description",
+	locale: "core.settings.kernel.locale",
+	localeDescription: "core.settings.kernel.locale-description",
+	localeEn: "core.settings.kernel.locale-en",
+	localeFr: "core.settings.kernel.locale-fr",
+} as const;
+
+/**
+ * The settings feature's strings, registered by the composition root alongside
+ * the core catalog.
+ */
+export const SETTINGS_CATALOG: KeyedCatalog<
+	| MessageKey<typeof SETTINGS_ISSUE_MESSAGES>
+	| MessageKey<typeof SETTINGS_MESSAGES>
+	| MessageKey<typeof KERNEL_SETTINGS_MESSAGES>
+> = {
+	[SETTINGS_ISSUE_MESSAGES.required]: {
+		en: "This setting is required.",
+		fr: "Ce paramètre est obligatoire.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.type]: {
+		en: "This value is not of the expected kind.",
+		fr: "Cette valeur n'est pas du type attendu.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.min]: {
+		en: "Must be at least {min}.",
+		fr: "Doit être au moins {min}.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.max]: {
+		en: "Must be at most {max}.",
+		fr: "Doit être au plus {max}.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.minLength]: {
+		en: "Must be at least {min} characters long.",
+		fr: "Doit contenir au moins {min} caractères.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.maxLength]: {
+		en: "Must be at most {max} characters long.",
+		fr: "Doit contenir au plus {max} caractères.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.minItems]: {
+		en: "Pick at least {min} items.",
+		fr: "Choisissez au moins {min} éléments.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.maxItems]: {
+		en: "Pick at most {max} items.",
+		fr: "Choisissez au plus {max} éléments.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.duplicate]: {
+		en: "The same value is listed more than once.",
+		fr: "La même valeur apparaît plusieurs fois.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.channelType]: {
+		en: "This type of channel is not allowed here.",
+		fr: "Ce type de salon n'est pas autorisé ici.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.notFound]: {
+		en: "This no longer exists on this server.",
+		fr: "Cet élément n'existe plus sur ce serveur.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.unknownChoice]: {
+		en: "This value is not one of the allowed choices.",
+		fr: "Cette valeur ne fait pas partie des choix autorisés.",
+	},
+	[SETTINGS_ISSUE_MESSAGES.unknownField]: {
+		en: "This setting does not exist.",
+		fr: "Ce paramètre n'existe pas.",
+	},
+	[SETTINGS_MESSAGES.secretSet]: { en: "Set", fr: "Défini" },
+	[SETTINGS_MESSAGES.secretNotSet]: { en: "Not set", fr: "Non défini" },
+	[SETTINGS_MESSAGES.valueUnavailable]: {
+		en: "A saved value is unavailable: it no longer exists on this server.",
+		fr: "Une valeur enregistrée est indisponible : elle n'existe plus sur ce serveur.",
+	},
+	[SETTINGS_MESSAGES.valueNotSet]: { en: "Not set", fr: "Non défini" },
+	[SETTINGS_MESSAGES.valueNone]: { en: "None", fr: "Aucun" },
+	[SETTINGS_MESSAGES.booleanTrue]: { en: "Yes", fr: "Oui" },
+	[SETTINGS_MESSAGES.booleanFalse]: { en: "No", fr: "Non" },
+	[SETTINGS_MESSAGES.moduleDisabled]: {
+		en: "This feature is disabled on this server.",
+		fr: "Cette fonctionnalité est désactivée sur ce serveur.",
+	},
+	[SETTINGS_MESSAGES.moduleNotConfigured]: {
+		en: "This feature is not configured on this server yet: an administrator must set it up first.",
+		fr: "Cette fonctionnalité n'est pas encore configurée sur ce serveur : un administrateur doit d'abord la configurer.",
+	},
+	[SETTINGS_MESSAGES.moduleNotConfiguredMissing]: {
+		en: "Missing settings: {fields}.",
+		fr: "Paramètres manquants : {fields}.",
+	},
+	[KERNEL_SETTINGS_MESSAGES.title]: { en: "Server", fr: "Serveur" },
+	[KERNEL_SETTINGS_MESSAGES.description]: {
+		en: "Features enabled on this server and the bot's language.",
+		fr: "Fonctionnalités activées sur ce serveur et langue du bot.",
+	},
+	[KERNEL_SETTINGS_MESSAGES.modules]: { en: "Features", fr: "Fonctionnalités" },
+	[KERNEL_SETTINGS_MESSAGES.modulesDescription]: {
+		en: "Turn a feature off to stop its commands, buttons and events on this server.",
+		fr: "Désactivez une fonctionnalité pour arrêter ses commandes, boutons et événements sur ce serveur.",
+	},
+	[KERNEL_SETTINGS_MESSAGES.locale]: { en: "Language", fr: "Langue" },
+	[KERNEL_SETTINGS_MESSAGES.localeDescription]: {
+		en: "The bot's language on this server, when a member's own language is not supported.",
+		fr: "La langue du bot sur ce serveur, lorsque la langue d'un membre n'est pas prise en charge.",
+	},
+	[KERNEL_SETTINGS_MESSAGES.localeEn]: { en: "English", fr: "Anglais" },
+	[KERNEL_SETTINGS_MESSAGES.localeFr]: { en: "French", fr: "Français" },
+};

package/src/settings/migrate.ts

@@ -0,0 +1,58 @@
+import { decodeStored } from "@/settings/decode-stored";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import { isPlainObject } from "@/settings/is-plain-object";
+import type { StoredSettings } from "@/settings/ports/settings-store";
+
+/**
+ * Outcome of {@link migrateStored}. Either way, `values` are the valid declared
+ * fields a guild reads; only an `ok` outcome may be written back (FR-018).
+ */
+export type MigrationOutcome =
+	| { readonly ok: true; readonly values: Readonly<Record<string, unknown>> }
+	| {
+			readonly ok: false;
+			readonly values: Readonly<Record<string, unknown>>;
+			/** The declared fields whose migrated value fails validation. */
+			readonly invalidKeys: readonly string[];
+			/** What the migration threw, or why its result was refused. */
+			readonly error?: unknown;
+	  };
+
+/**
+ * Reshape values stored under an older declaration version with the
+ * declaration's `migrate`, then validate the result through the same checks
+ * as any stored value. Pure: it reads and writes nothing, and hands `migrate` a
+ * copy, so the stored record is never touched.
+ *
+ * - `migrate` throws, is missing, or returns anything but a plain object: not
+ *   `ok`, and `values` are the stored values that still validate as they are.
+ * - Some migrated field fails validation: not `ok`, and `values` are the
+ *   migrated fields that validate.
+ * - Otherwise `ok`, with every migrated declared field; undeclared keys the
+ *   migration returns are dropped.
+ *
+ * @param declaration - the module's current declaration.
+ * @param stored - a record whose `version` is below `declaration.version`.
+ */
+export function migrateStored(
+	declaration: SettingsDeclaration,
+	stored: Pick<StoredSettings, "version" | "values">,
+): MigrationOutcome {
+	let migrated: unknown;
+	try {
+		if (declaration.migrate === undefined) {
+			throw new Error(`module "${declaration.id}" declares no migration`);
+		}
+		migrated = declaration.migrate(stored.version, structuredClone(stored.values));
+	} catch (error) {
+		return { ok: false, error, ...decodeStored(declaration, stored.values) };
+	}
+	if (!isPlainObject(migrated)) {
+		const error = new Error(`the migration of module "${declaration.id}" returned no plain object`);
+		return { ok: false, error, ...decodeStored(declaration, stored.values) };
+	}
+	const decoded = decodeStored(declaration, migrated);
+	return decoded.invalidKeys.length === 0
+		? { ok: true, values: decoded.values }
+		: { ok: false, ...decoded };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Vendor-free channel category a channel field can be restricted to. Each
+ * member maps one to one to a guild channel type of Discord's `ChannelType`.
+ */
+export type ChannelKind =
+	/** `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";
+
+/**
+ * Read-only view of a guild's channels, roles and members. Settings logic uses
+ * it to check that a referenced entity exists and to suggest candidates,
+ * without depending on discord.js.
+ */
+export interface GuildDirectory {
+	channel(
+		guildId: string,
+		id: string,
+	): Promise<{ id: string; name: string; kind: ChannelKind } | null>;
+	role(guildId: string, id: string): Promise<{ id: string; name: string } | null>;
+	member(guildId: string, id: string): Promise<{ id: string; name: string } | null>;
+	searchChannels(
+		guildId: string,
+		query: string,
+		kinds?: readonly ChannelKind[],
+	): Promise<readonly { id: string; name: string; kind: ChannelKind }[]>;
+	searchRoles(guildId: string, query: string): Promise<readonly { id: string; name: string }[]>;
+	searchMembers(guildId: string, query: string): Promise<readonly { id: string; name: string }[]>;
+}

package/src/settings/ports/settings-changed-notifier.ts

@@ -0,0 +1,20 @@
+/** Emitted after a module's settings changed for a guild. */
+export interface SettingsChangedEvent {
+	readonly guildId: string;
+	readonly moduleId: string;
+	readonly changedKeys: readonly string[];
+	/** Revision of the record after the change. */
+	readonly revision: number;
+	/** Snowflake of the user who made the change. */
+	readonly changedBy?: string;
+}
+
+/**
+ * Broadcasts settings changes, e.g. so read caches can invalidate. The default
+ * implementation is in-process; distributed delivery is a separate adapter.
+ */
+export interface SettingsChangedNotifier {
+	notify(event: SettingsChangedEvent): void;
+	/** Register `listener`; the returned function unsubscribes it. */
+	subscribe(listener: (event: SettingsChangedEvent) => void): () => void;
+}

package/src/settings/ports/settings-store.ts

@@ -0,0 +1,74 @@
+/**
+ * The record a {@link SettingsStore} persists, one per `(guildId, moduleId)`.
+ * Every field is JSON-serialisable, so an adapter may store the record as one
+ * document, one row with a JSON column, or one hash; it must give back an equal
+ * record (`updatedBy` absent stays absent).
+ */
+export interface StoredSettings {
+	readonly guildId: string;
+	/** Equals the declaration id of the module that owns these values. */
+	readonly moduleId: string;
+	/** Declaration version the values were written under. */
+	readonly version: number;
+	/**
+	 * Starts at 1 on first write; +1 on each write. Used for optimistic
+	 * concurrency. The caller computes it; the store persists it as given.
+	 */
+	readonly revision: number;
+	/**
+	 * Only declared, valid fields; unset fields are absent. Every value is plain
+	 * JSON (string, finite number, boolean, `null`, arrays and objects of those),
+	 * so `JSON.stringify` then `JSON.parse` gives back an equal object.
+	 */
+	readonly values: Readonly<Record<string, unknown>>;
+	/** ISO-8601 timestamp from the `Clock` port. */
+	readonly updatedAt: string;
+	/** Snowflake of the user who made the change. */
+	readonly updatedBy?: string;
+}
+
+/**
+ * Persistence port for module settings: the kernel's only view of a database.
+ * An adapter over any engine (a JSON file, SQLite, Postgres, MongoDB, Redis)
+ * implements it in the bot or in an opt-in package, never in the kernel, and
+ * proves it with `runSettingsStoreContract` from
+ * `@azurioh/discord-kernel/settings/testing`.
+ *
+ * Guarantees every implementation must honour:
+ *
+ * - **Isolation.** A record is keyed by `(guildId, moduleId)`; reading, writing
+ *   or deleting one key never touches another.
+ * - **Atomic compare-and-set.** `write` checks the stored revision and replaces
+ *   the record in one atomic step of the engine, so that of several writers
+ *   holding the same `expectedRevision` (Discord shards, an HTTP API) exactly
+ *   one wins and the others get `ConflictError`.
+ * - **Independent copies.** The store never keeps a reference to the record it
+ *   was given nor hands out one it keeps: callers may mutate what they pass in
+ *   or get back without changing what is stored.
+ * - **Errors are real.** Only a revision mismatch is a `ConflictError`; any
+ *   other failure (connection lost, corrupt data) is thrown as it is.
+ */
+export interface SettingsStore {
+	/**
+	 * The record of one module in one guild.
+	 *
+	 * @returns a copy of the stored record, or `null` when none was written yet
+	 * (or it was deleted).
+	 */
+	read(guildId: string, moduleId: string): Promise<StoredSettings | null>;
+	/**
+	 * Persist `record` as a whole, replacing any stored one, if and only if the
+	 * stored revision is `expectedRevision`.
+	 *
+	 * @param opts.expectedRevision - the revision the caller read; `null` means
+	 * no record may exist yet (a create).
+	 * @throws ConflictError when the stored revision (or `null` for no record)
+	 * differs from `expectedRevision`. The stored record is then left unchanged.
+	 */
+	write(record: StoredSettings, opts: { expectedRevision: number | null }): Promise<void>;
+	/**
+	 * Remove the record of one module in one guild, whatever its revision.
+	 * Idempotent: deleting a missing record succeeds and does nothing.
+	 */
+	delete(guildId: string, moduleId: string): Promise<void>;
+}

package/src/settings/registry.ts

@@ -0,0 +1,137 @@
+import type { TranslationRegistry } from "@/i18n/catalog";
+import type { SettingsDeclaration } from "@/settings/define-settings";
+import {
+	type AnyField,
+	type FieldChoice,
+	type FieldSpec,
+	type Suggestions,
+	unhandledFieldKind,
+} from "@/settings/fields/field";
+import { SettingsDeclarationError } from "@/settings/settings-declaration-error";
+import {
+	type KernelSettings,
+	kernelSettings,
+	type ModuleEnablement,
+} from "@/settings/system/kernel-settings";
+
+/** Every settings declaration of the bot, checked at boot. */
+export interface SettingsRegistry {
+	/** The kernel's own declaration first, then the modules' in registration order. */
+	readonly declarations: readonly SettingsDeclaration[];
+	/** The kernel's own declaration (id `kernel`), built from the registered modules. */
+	readonly kernel: KernelSettings;
+	get(id: string): SettingsDeclaration | undefined;
+}
+
+/**
+ * Collect the modules' settings declarations at boot, after the kernel's own
+ * declaration ({@link kernelSettings}), which is always included.
+ *
+ * @param input.declarations - every module's declaration.
+ * @param input.translations - must already contain the modules' catalogs and
+ * `SETTINGS_CATALOG`, which holds the kernel declaration's texts.
+ * @param input.modules - the registered modules (a `BotModule` fits), whose
+ * names and `defaultEnabled` build the kernel's module toggles. None by default.
+ * @returns the registry of declarations, by id.
+ * @throws SettingsDeclarationError when two declarations share an id (FR-005)
+ * or a declaration references a catalog key without an English source (FR-028),
+ * or two modules share a name.
+ */
+export function createSettingsRegistry(input: {
+	declarations: readonly SettingsDeclaration[];
+	translations: TranslationRegistry;
+	modules?: readonly ModuleEnablement[];
+}): SettingsRegistry {
+	const kernel = kernelSettings(input.modules ?? []);
+	const byId = new Map<string, SettingsDeclaration>();
+	for (const declaration of [kernel, ...input.declarations]) {
+		if (byId.has(declaration.id)) {
+			throw new SettingsDeclarationError(declaration.id, "is declared more than once");
+		}
+		checkKeys({ declaration, translations: input.translations });
+		byId.set(declaration.id, declaration);
+	}
+	return {
+		declarations: [...byId.values()],
+		kernel,
+		get: (id) => byId.get(id),
+	};
+}
+
+function checkKeys(params: {
+	declaration: SettingsDeclaration;
+	translations: TranslationRegistry;
+}): void {
+	const { declaration, translations } = params;
+	for (const key of catalogKeys(declaration)) {
+		if (!translations.has(key)) {
+			throw new SettingsDeclarationError(
+				declaration.id,
+				`catalog key "${key}" has no English source`,
+			);
+		}
+	}
+}
+
+/**
+ * Every catalog key a declaration references: labels, groups, fields, choices
+ * and toggle key labels.
+ */
+function* catalogKeys(declaration: SettingsDeclaration): Generator<string> {
+	yield* defined([declaration.labels.title, declaration.labels.description]);
+	for (const group of Object.values(declaration.groups ?? {})) {
+		yield* defined([group.label, group.description]);
+	}
+	for (const declared of Object.values(declaration.fields)) {
+		yield* fieldKeys(declared);
+	}
+}
+
+function* fieldKeys(declared: AnyField): Generator<string> {
+	yield* defined([declared.label, declared.description, declared.placeholder, declared.unit]);
+	yield* specKeys(declared.spec);
+}
+
+function* specKeys(spec: FieldSpec): Generator<string> {
+	switch (spec.kind) {
+		case "enum":
+			yield* spec.choices.map(choiceLabel);
+			return;
+		case "integer":
+		case "text":
+			yield* suggestionKeys(spec.suggest);
+			return;
+		case "list":
+			yield* fieldKeys(spec.item);
+			return;
+		case "toggles":
+			yield* defined(Object.values(spec.keyLabels ?? {}));
+			return;
+		case "channel":
+		case "role":
+		case "user":
+		case "color":
+		case "duration":
+		case "number":
+		case "boolean":
+		case "secret":
+			return;
+		default:
+			unhandledFieldKind(spec);
+	}
+}
+
+function suggestionKeys(suggest: Suggestions<unknown> | undefined): string[] {
+	if (suggest === undefined || !("choices" in suggest)) {
+		return [];
+	}
+	return suggest.choices.map(choiceLabel);
+}
+
+function choiceLabel(choice: FieldChoice<unknown>): string {
+	return choice.label;
+}
+
+function defined(keys: readonly (string | undefined)[]): string[] {
+	return keys.filter((key) => key !== undefined);
+}

package/src/settings/settings-declaration-error.ts

@@ -0,0 +1,16 @@
+/**
+ * A module's settings declaration breaks a rule that can be checked without a
+ * guild: a default failing its own field, a secret with a default, too many
+ * choices, a duplicate id, a catalog key with no English source… Raised by
+ * `defineSettings` and `createSettingsRegistry` at boot, so a broken
+ * declaration never reaches a server.
+ */
+export class SettingsDeclarationError extends Error {
+	constructor(
+		readonly declarationId: string,
+		readonly reason: string,
+	) {
+		super(`Settings declaration "${declarationId}": ${reason}`);
+		this.name = "SettingsDeclarationError";
+	}
+}