@azurioh/discord-kernel 0.1.0 → 1.0.0

package/src/settings/suggest.ts

@@ -0,0 +1,267 @@
+import { MAX_AUTOCOMPLETE_CHOICES } from "@/discord/command/autocomplete-limits";
+import { resolveLocale } from "@/i18n/locale";
+import type { Translator } from "@/i18n/translator";
+import type { Logger } from "@/logger";
+import type { Choice } from "@/settings/choice";
+import {
+	type DynamicSuggestions,
+	type FieldChoice,
+	type FieldSpec,
+	type SuggestionContext,
+	type Suggestions,
+	unhandledFieldKind,
+} from "@/settings/fields/field";
+import type { GuildDirectory } from "@/settings/ports/guild-directory";
+import { timedSearch } from "@/settings/timed-search";
+
+/**
+ * The ports suggestions read: the guild's directory, the translator of static
+ * labels, and where a slow or failed search is logged.
+ */
+export interface SuggestionPorts {
+	readonly guilds: GuildDirectory;
+	readonly translator: Translator;
+	readonly logger: Logger;
+}
+
+/** What one field's suggestions are computed with: the ports, the field, and who asks. */
+export interface SuggestionScope extends SuggestionPorts {
+	readonly moduleId: string;
+	/** The field's key, named in logs. */
+	readonly key: string;
+	readonly ctx: SuggestionContext;
+}
+
+/** A search the kernel runs on the module's behalf, whatever the value type it suggests. */
+type AnyDynamicSuggestions = DynamicSuggestions<unknown>;
+
+/**
+ * The suggestions of one field for `query` (FR-021, FR-025): a channel, role
+ * or member field searches the guild; an enum and static suggestions offer
+ * their choices translated to the requester's locale, those whose name or
+ * value contains the query (case-insensitive); a dynamic search gets the
+ * query and the context as is. A list suggests for its item. At most
+ * {@link MAX_AUTOCOMPLETE_CHOICES} results, the first ones kept; a search
+ * slower than the budget or failing yields none (logged). Never throws.
+ *
+ * @param params.scope - who asks and the ports the search reads.
+ * @param params.spec - the field's kind and constraints.
+ * @param params.query - what was typed so far; empty for a first page.
+ * @returns the suggestions, labels already translated.
+ */
+export async function suggestChoices(params: {
+	scope: SuggestionScope;
+	spec: FieldSpec;
+	query: string;
+}): Promise<readonly Choice[]> {
+	const choices = await allChoices(params);
+	return choices.slice(0, MAX_AUTOCOMPLETE_CHOICES);
+}
+
+async function allChoices(params: {
+	scope: SuggestionScope;
+	spec: FieldSpec;
+	query: string;
+}): Promise<readonly Choice[]> {
+	const { scope, spec, query } = params;
+	const { guilds, ctx } = scope;
+	switch (spec.kind) {
+		case "channel":
+			return timed({
+				scope,
+				fallback: [],
+				search: async () => named(await guilds.searchChannels(ctx.guildId, query, spec.types)),
+			});
+		case "role":
+			return timed({
+				scope,
+				fallback: [],
+				search: async () => named(await guilds.searchRoles(ctx.guildId, query)),
+			});
+		case "user":
+			return timed({
+				scope,
+				fallback: [],
+				search: async () => named(await guilds.searchMembers(ctx.guildId, query)),
+			});
+		case "enum":
+			return matching({ choices: translated({ scope, choices: spec.choices }), query });
+		case "integer":
+		case "text":
+			return declaredChoices({ scope, suggest: spec.suggest, query });
+		case "list":
+			return allChoices({ scope, spec: spec.item.spec, query });
+		case "color":
+		case "duration":
+		case "number":
+		case "boolean":
+		case "secret":
+		case "toggles":
+			return [];
+		default:
+			return unhandledFieldKind(spec);
+	}
+}
+
+/** The suggestions a module declared on an integer or text field, if any. */
+async function declaredChoices(params: {
+	scope: SuggestionScope;
+	suggest: Suggestions<string> | Suggestions<number> | undefined;
+	query: string;
+}): Promise<readonly Choice[]> {
+	const { scope, suggest, query } = params;
+	if (suggest === undefined) {
+		return [];
+	}
+	if ("choices" in suggest) {
+		return matching({ choices: translated({ scope, choices: suggest.choices }), query });
+	}
+	const search: AnyDynamicSuggestions = suggest;
+	return timed({ scope, fallback: [], search: () => search.resolve(query, scope.ctx) });
+}
+
+/**
+ * The readable label of one stored value of a field, in the requester's
+ * locale: a channel, role or member's name on the guild, a static choice's
+ * translated label, or what a dynamic search says (see {@link dynamicLabel}).
+ * A list reads `value` as one of its items. Never throws.
+ *
+ * @param params.scope - who asks and the ports the label reads.
+ * @param params.spec - the field's kind and constraints.
+ * @param params.value - the stored value.
+ * @returns the label, or `undefined` when none is known.
+ */
+export async function suggestionLabel(params: {
+	scope: SuggestionScope;
+	spec: FieldSpec;
+	value: unknown;
+}): Promise<string | undefined> {
+	const { scope, spec, value } = params;
+	const { guilds, ctx } = scope;
+	switch (spec.kind) {
+		case "channel":
+			return entityName({ scope, find: (id) => guilds.channel(ctx.guildId, id), value });
+		case "role":
+			return entityName({ scope, find: (id) => guilds.role(ctx.guildId, id), value });
+		case "user":
+			return entityName({ scope, find: (id) => guilds.member(ctx.guildId, id), value });
+		case "enum":
+			return staticLabel({ scope, choices: spec.choices, value });
+		case "integer":
+		case "text":
+			if (spec.suggest === undefined) {
+				return undefined;
+			}
+			return "choices" in spec.suggest
+				? staticLabel({ scope, choices: spec.suggest.choices, value })
+				: dynamicLabel({ scope, suggest: spec.suggest, value });
+		case "list":
+			return suggestionLabel({ scope, spec: spec.item.spec, value });
+		case "color":
+		case "duration":
+		case "number":
+		case "boolean":
+		case "secret":
+		case "toggles":
+			return undefined;
+		default:
+			return unhandledFieldKind(spec);
+	}
+}
+
+/**
+ * What a dynamic search calls `value` (FR-022): its own `label` when it
+ * declares one, otherwise the name of the result of `resolve(String(value))`
+ * whose value is exactly `value`. `undefined` when the search does not know
+ * the value, or runs past the budget or fails (logged). A strict field
+ * accepts exactly the values this labels (FR-023).
+ *
+ * @param params.scope - who asks, and where a slow or failed search is logged.
+ * @param params.suggest - the field's search.
+ * @param params.value - the value to label.
+ * @returns the label, or `undefined`.
+ */
+export function dynamicLabel(params: {
+	scope: SuggestionScope;
+	suggest: AnyDynamicSuggestions;
+	value: unknown;
+}): Promise<string | undefined> {
+	const { scope, suggest, value } = params;
+	const { label } = suggest;
+	if (label !== undefined) {
+		return timed({ scope, fallback: undefined, search: () => label(value, scope.ctx) });
+	}
+	return timed({
+		scope,
+		fallback: undefined,
+		search: async () => {
+			const results = await suggest.resolve(String(value), scope.ctx);
+			return results.find((choice) => choice.value === value)?.name;
+		},
+	});
+}
+
+/** A search within the suggestion budget, logged under the scope's module, field and guild. */
+function timed<T>(params: {
+	scope: SuggestionScope;
+	fallback: T;
+	search: () => Promise<T>;
+}): Promise<T> {
+	const { scope, fallback, search } = params;
+	return timedSearch({
+		search,
+		fallback,
+		logger: scope.logger,
+		at: { moduleId: scope.moduleId, field: scope.key, guildId: scope.ctx.guildId },
+	});
+}
+
+/** The name of the guild entity a stored id names, if the guild still has it. */
+function entityName(params: {
+	scope: SuggestionScope;
+	find: (id: string) => Promise<{ readonly name: string } | null>;
+	value: unknown;
+}): Promise<string | undefined> {
+	const { scope, find, value } = params;
+	if (typeof value !== "string") {
+		return Promise.resolve(undefined);
+	}
+	return timed({ scope, fallback: undefined, search: async () => (await find(value))?.name });
+}
+
+/** Guild entities as choices: their name shown, their id stored. */
+function named(entities: readonly { readonly id: string; readonly name: string }[]): Choice[] {
+	return entities.map((entity) => ({ name: entity.name, value: entity.id }));
+}
+
+/** Static choices with their labels translated to the requester's locale. */
+function translated(params: {
+	scope: SuggestionScope;
+	choices: readonly FieldChoice<string | number>[];
+}): Choice[] {
+	const { scope, choices } = params;
+	const locale = resolveLocale([scope.ctx.locale], scope.translator.defaultLocale);
+	return choices.map((choice) => ({
+		name: scope.translator.translate(locale, choice.label),
+		value: choice.value,
+	}));
+}
+
+/** The choices whose name or value contains `query`, case-insensitive; all of them for an empty query. */
+function matching(params: { choices: readonly Choice[]; query: string }): readonly Choice[] {
+	const needle = params.query.trim().toLowerCase();
+	return params.choices.filter(
+		(choice) =>
+			choice.name.toLowerCase().includes(needle) ||
+			String(choice.value).toLowerCase().includes(needle),
+	);
+}
+
+/** The translated label of the static choice storing `value`. */
+function staticLabel(params: {
+	scope: SuggestionScope;
+	choices: readonly FieldChoice<string | number>[];
+	value: unknown;
+}): string | undefined {
+	return translated(params).find((choice) => choice.value === params.value)?.name;
+}

package/src/settings/system/kernel-settings.ts

@@ -0,0 +1,74 @@
+import { type Locale, SUPPORTED_LOCALES } from "@/i18n/locale";
+import { defineSettings } from "@/settings/define-settings";
+import { field } from "@/settings/fields/builders";
+import { KERNEL_SETTINGS_MESSAGES } from "@/settings/messages";
+
+/** Id of the kernel's own settings declaration. */
+export const KERNEL_SETTINGS_ID = "kernel";
+
+/**
+ * What the kernel declaration needs to know of a module. A `BotModule`
+ * satisfies it as is, so the composition root passes its modules unchanged.
+ */
+export interface ModuleEnablement {
+	readonly name: string;
+	/**
+	 * Catalog key of the module's name as administrators read it, shown on its
+	 * toggle. Without one the toggle shows the raw module name, and the translator
+	 * logs it as an unknown key: give every toggleable module a label.
+	 */
+	readonly label?: string;
+	/** Whether the module starts enabled in a guild that never toggled it. Defaults to `true`. */
+	readonly defaultEnabled?: boolean;
+}
+
+const LOCALE_LABELS: Readonly<Record<Locale, string>> = {
+	en: KERNEL_SETTINGS_MESSAGES.localeEn,
+	fr: KERNEL_SETTINGS_MESSAGES.localeFr,
+};
+
+/**
+ * The kernel's own settings, declared like any module's (FR-039): which
+ * modules are enabled on the guild, and the bot's language there.
+ *
+ * A factory rather than a constant because the module names are only known at
+ * composition: `createSettingsRegistry` calls it with the modules it receives.
+ *
+ * @param modules - the registered modules, in registration order.
+ * @returns the declaration of id {@link KERNEL_SETTINGS_ID}.
+ * @throws SettingsDeclarationError when two modules share a name.
+ */
+export function kernelSettings(modules: readonly ModuleEnablement[]) {
+	return defineSettings({
+		id: KERNEL_SETTINGS_ID,
+		version: 1,
+		labels: {
+			title: KERNEL_SETTINGS_MESSAGES.title,
+			description: KERNEL_SETTINGS_MESSAGES.description,
+		},
+		fields: {
+			modules: field.toggles<string>({
+				label: KERNEL_SETTINGS_MESSAGES.modules,
+				description: KERNEL_SETTINGS_MESSAGES.modulesDescription,
+				keys: modules.map(({ name }) => name),
+				keyLabels: Object.fromEntries(
+					modules.flatMap(({ name, label }) => (label === undefined ? [] : [[name, label]])),
+				),
+				default: Object.fromEntries(
+					modules.map(({ name, defaultEnabled }) => [name, defaultEnabled ?? true]),
+				),
+			}),
+			locale: field.enum({
+				label: KERNEL_SETTINGS_MESSAGES.locale,
+				description: KERNEL_SETTINGS_MESSAGES.localeDescription,
+				choices: SUPPORTED_LOCALES.map((locale) => ({
+					value: locale,
+					label: LOCALE_LABELS[locale],
+				})),
+			}),
+		},
+	});
+}
+
+/** The kernel's settings declaration, as built by {@link kernelSettings}. */
+export type KernelSettings = ReturnType<typeof kernelSettings>;

package/src/settings/system/module-gate.ts

@@ -0,0 +1,49 @@
+import { errorMessage } from "@/errors/error-message";
+import type { Logger } from "@/logger";
+import type { SettingsRegistry } from "@/settings/registry";
+import type { SettingsService } from "@/settings/settings-service";
+
+/**
+ * Whether a module runs on a guild. The command, component and event routers
+ * check it before running a module's handler there; scheduled jobs call it
+ * themselves (FR-036).
+ */
+export interface ModuleGate {
+	isEnabled(moduleName: string, guildId: string): Promise<boolean>;
+}
+
+/**
+ * Create the gate over the guild's kernel settings (`registry.kernel`), read
+ * through the service's cache, so checking it on every interaction does not
+ * hit the store.
+ *
+ * A module the kernel declaration does not know is never gated. When the
+ * settings cannot be read, the module runs and the error is logged: a store
+ * outage must not switch every module off.
+ *
+ * @param deps.service - reads the guild's kernel settings.
+ * @param deps.registry - holds the kernel declaration built from the modules.
+ * @param deps.logger - where a failed read is reported.
+ * @returns the gate shared by the routers and the scheduled jobs.
+ */
+export function createModuleGate(deps: {
+	service: SettingsService;
+	registry: SettingsRegistry;
+	logger: Logger;
+}): ModuleGate {
+	const { service, registry, logger } = deps;
+	return {
+		async isEnabled(moduleName: string, guildId: string): Promise<boolean> {
+			try {
+				const { modules } = await service.get(registry.kernel, guildId);
+				return modules[moduleName] ?? true;
+			} catch (error) {
+				logger.error(
+					{ module: moduleName, guildId, err: errorMessage(error) },
+					"Could not read whether the module is enabled; letting it run",
+				);
+				return true;
+			}
+		},
+	};
+}

package/src/settings/testing/index.ts

@@ -0,0 +1,7 @@
+export {
+	type ContractAssertion,
+	type DescribeFn,
+	type ExpectFn,
+	type ItFn,
+	runSettingsStoreContract,
+} from "@/settings/testing/settings-store-contract";

package/src/settings/testing/settings-store-contract.ts

@@ -0,0 +1,278 @@
+import { ConflictError } from "@/errors/business-error";
+import type { SettingsStore, StoredSettings } from "@/settings/ports/settings-store";
+
+/** Minimal shape of a test runner's `describe`, so this suite imports no framework. */
+export type DescribeFn = (name: string, body: () => void) => void;
+
+/** Minimal shape of a test runner's `it`. */
+export type ItFn = (name: string, body: () => Promise<void>) => void;
+
+/** The assertions this suite relies on; Vitest's and Jest's `expect` both satisfy it. */
+export interface ContractAssertion {
+	toBe(expected: unknown): void;
+	toEqual(expected: unknown): void;
+	toBeNull(): void;
+	toBeInstanceOf(expected: abstract new (...args: never[]) => unknown): void;
+}
+
+/** Minimal shape of a test runner's `expect`. */
+export type ExpectFn = (actual: unknown) => ContractAssertion;
+
+const GUILD_A = "100000000000000001";
+const GUILD_B = "100000000000000002";
+const MODULE_A = "tickets";
+const MODULE_B = "welcome";
+
+function record(overrides: Partial<StoredSettings> = {}): StoredSettings {
+	return {
+		guildId: GUILD_A,
+		moduleId: MODULE_A,
+		version: 1,
+		revision: 1,
+		values: { maxOpen: 2 },
+		updatedAt: "2026-01-01T00:00:00.000Z",
+		updatedBy: "200000000000000001",
+		...overrides,
+	};
+}
+
+async function captureError(action: () => Promise<unknown>): Promise<unknown> {
+	try {
+		await action();
+	} catch (error) {
+		return error;
+	}
+	return undefined;
+}
+
+/** The caller's view of a record it may scribble on, to prove the store kept its own copy. */
+function mutableValues(stored: StoredSettings | null): Record<string, unknown> {
+	return (stored?.values ?? {}) as Record<string, unknown>;
+}
+
+/**
+ * Behaviour every {@link SettingsStore} implementation must have: one case per
+ * guarantee stated on the port. Run it from the adapter's own test file with
+ * the test runner's `describe`, `it` and `expect`:
+ * `runSettingsStoreContract(createMyStore, { describe, it, expect })`.
+ *
+ * @param createStore - returns a store with no record in it; called once per case.
+ * @param runner - the test runner's functions, so this suite imports no framework.
+ */
+export function runSettingsStoreContract(
+	createStore: () => SettingsStore | Promise<SettingsStore>,
+	runner: { describe: DescribeFn; it: ItFn; expect: ExpectFn },
+): void {
+	const { describe, it, expect } = runner;
+
+	/**
+	 * Deleting the default record must leave `other` — the same record moved to
+	 * another guild or another module — exactly as it was written.
+	 */
+	async function expectDeleteLeavesAlone(other: StoredSettings): Promise<void> {
+		const store = await createStore();
+		await store.write(record(), { expectedRevision: null });
+		await store.write(other, { expectedRevision: null });
+
+		await store.delete(GUILD_A, MODULE_A);
+
+		expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+		expect(await store.read(other.guildId, other.moduleId)).toEqual(other);
+	}
+
+	describe("SettingsStore contract", () => {
+		it("reads null when no record exists", async () => {
+			const store = await createStore();
+
+			expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+		});
+
+		it("creates a record when the expected revision is null", async () => {
+			const store = await createStore();
+			const created = record();
+
+			await store.write(created, { expectedRevision: null });
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(created);
+		});
+
+		it("rejects a create when a record already exists", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+
+			const error = await captureError(() =>
+				store.write(record({ values: { maxOpen: 3 } }), { expectedRevision: null }),
+			);
+
+			expect(error).toBeInstanceOf(ConflictError);
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+		});
+
+		it("rejects an update when no record exists", async () => {
+			const store = await createStore();
+
+			const error = await captureError(() =>
+				store.write(record({ revision: 2 }), { expectedRevision: 1 }),
+			);
+
+			expect(error).toBeInstanceOf(ConflictError);
+			expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+		});
+
+		it("rejects a write with a stale revision and keeps the stored record", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+			const second = record({ revision: 2, values: { maxOpen: 3 } });
+			await store.write(second, { expectedRevision: 1 });
+
+			const error = await captureError(() =>
+				store.write(record({ revision: 2, values: { maxOpen: 4 } }), { expectedRevision: 1 }),
+			);
+
+			expect(error).toBeInstanceOf(ConflictError);
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(second);
+		});
+
+		it("increments the revision by one on each write", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+			await store.write(record({ revision: 2 }), { expectedRevision: 1 });
+			await store.write(record({ revision: 3 }), { expectedRevision: 2 });
+
+			const stored = await store.read(GUILD_A, MODULE_A);
+
+			expect(stored?.revision).toBe(3);
+		});
+
+		it("deletes a record", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+
+			await store.delete(GUILD_A, MODULE_A);
+
+			expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+		});
+
+		it("deletes a missing record without error", async () => {
+			const store = await createStore();
+
+			const error = await captureError(() => store.delete(GUILD_A, MODULE_A));
+
+			expect(error).toBe(undefined);
+			expect(await store.read(GUILD_A, MODULE_A)).toBeNull();
+		});
+
+		it("accepts a create again after a delete", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+			await store.delete(GUILD_A, MODULE_A);
+
+			await store.write(record(), { expectedRevision: null });
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+		});
+
+		it("keeps guilds isolated", async () => {
+			await expectDeleteLeavesAlone(record({ guildId: GUILD_B, values: { maxOpen: 5 } }));
+		});
+
+		it("keeps modules isolated", async () => {
+			await expectDeleteLeavesAlone(record({ moduleId: MODULE_B, values: { greeting: "hi" } }));
+		});
+
+		it("round-trips every JSON value shape", async () => {
+			const store = await createStore();
+			const created = record({
+				values: {
+					text: "Salut « à vous » 👋",
+					count: -1.5,
+					enabled: false,
+					cleared: null,
+					roles: ["300000000000000001", "300000000000000002"],
+					nested: { toggles: { a: true }, list: [] },
+				},
+			});
+
+			await store.write(created, { expectedRevision: null });
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(created);
+		});
+
+		it("keeps an absent updatedBy absent", async () => {
+			const store = await createStore();
+			const { updatedBy: _omitted, ...anonymous } = record();
+
+			await store.write(anonymous, { expectedRevision: null });
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(anonymous);
+		});
+
+		it("keeps a written record independent of the caller's object", async () => {
+			const store = await createStore();
+			const written = record();
+			await store.write(written, { expectedRevision: null });
+
+			mutableValues(written).maxOpen = 99;
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+		});
+
+		it("returns a record the caller can change without changing the store", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+
+			mutableValues(await store.read(GUILD_A, MODULE_A)).maxOpen = 99;
+
+			expect(await store.read(GUILD_A, MODULE_A)).toEqual(record());
+		});
+
+		it("lets exactly one of two concurrent creates win", async () => {
+			const store = await createStore();
+			const first = record({ values: { maxOpen: 3 } });
+			const second = record({ values: { maxOpen: 4 } });
+
+			const outcomes = await Promise.allSettled([
+				store.write(first, { expectedRevision: null }),
+				store.write(second, { expectedRevision: null }),
+			]);
+
+			await expectOneWinner(store, outcomes, [first, second]);
+		});
+
+		it("lets exactly one of two concurrent updates of the same revision win", async () => {
+			const store = await createStore();
+			await store.write(record(), { expectedRevision: null });
+			const first = record({ revision: 2, values: { maxOpen: 3 } });
+			const second = record({ revision: 2, values: { maxOpen: 4 } });
+
+			const outcomes = await Promise.allSettled([
+				store.write(first, { expectedRevision: 1 }),
+				store.write(second, { expectedRevision: 1 }),
+			]);
+
+			await expectOneWinner(store, outcomes, [first, second]);
+		});
+	});
+
+	/**
+	 * Of two racing writes, exactly one lands, the other fails with a
+	 * `ConflictError`, and the stored record is the winner's.
+	 */
+	async function expectOneWinner(
+		store: SettingsStore,
+		outcomes: readonly PromiseSettledResult<void>[],
+		written: readonly [StoredSettings, StoredSettings],
+	): Promise<void> {
+		const winners = outcomes.flatMap((outcome, index) =>
+			outcome.status === "fulfilled" ? [written[index]] : [],
+		);
+		const losers = outcomes.flatMap((outcome) =>
+			outcome.status === "rejected" ? [outcome.reason] : [],
+		);
+
+		expect(winners.length).toBe(1);
+		expect(losers.length).toBe(1);
+		expect(losers[0]).toBeInstanceOf(ConflictError);
+		expect(await store.read(GUILD_A, MODULE_A)).toEqual(winners[0]);
+	}
+}