@azurioh/discord-kernel 0.1.0 → 1.0.0

package/README.md

@@ -51,6 +51,300 @@ import { type Catalog, createTranslator } from "@azurioh/discord-kernel/i18n";
 - **A palette.** Embeds render in Discord's blurple until you say otherwise, so a
   bot never starts out wearing someone else's identity.
 
+## Module settings
+
+A module declares its per-guild settings once. The kernel then validates,
+stores, caches and reads them, and builds the Discord settings screen, the
+autocomplete suggestions and a JSON Schema for other surfaces (a web
+dashboard) from that single declaration. Everything lives behind two entry
+points: `@azurioh/discord-kernel/settings` and, for tests,
+`@azurioh/discord-kernel/settings/testing`.
+
+### Declaring settings
+
+Every text is a catalog key (with an English source), never a literal:
+
+```ts
+import { defineSettings, field } from "@azurioh/discord-kernel/settings";
+
+export const tickets = defineSettings({
+  id: "tickets",
+  version: 1,
+  labels: { title: "tickets.settings.title" },
+  groups: { routing: { label: "tickets.settings.routing" } },
+  fields: {
+    channel: field.channel({ label: "tickets.channel", types: ["text"], required: true, ui: { group: "routing" } }),
+    staffRole: field.role({ label: "tickets.staff-role", ui: { group: "routing" } }),
+    maxOpen: field.integer({ label: "tickets.max-open", min: 1, max: 10, default: 3 }),
+    cooldown: field.duration({ label: "tickets.cooldown", default: 300 }), // seconds, typed as `5m`
+    mode: field.enum({
+      label: "tickets.mode",
+      choices: [
+        { value: "open", label: "tickets.mode.open" },
+        { value: "closed", label: "tickets.mode.closed" },
+      ],
+      default: "open",
+    }),
+    apiKey: field.secret({ label: "tickets.api-key" }),
+    pingRoles: field.list(field.role(), { label: "tickets.ping-roles", maxItems: 5, default: [] }),
+  },
+});
+```
+
+Field kinds: `text`, `integer`, `number`, `boolean`, `enum`, `color`,
+`duration`, `channel`, `role`, `user`, `secret`, `list` and `toggles`. Give the
+declarations to a `BotModule` (`settings: [tickets]`), then build the registry
+and the service once, in the composition root:
+
+```ts
+import { createDiscordGuildDirectory } from "@azurioh/discord-kernel/discord/settings/discord-guild-directory";
+import {
+  createInProcessNotifier,
+  createSettingsRegistry,
+  createSettingsService,
+  SETTINGS_CATALOG,
+} from "@azurioh/discord-kernel/settings";
+
+translations.register(SETTINGS_CATALOG); // with CORE_CATALOG and every module's catalog
+const registry = createSettingsRegistry({
+  declarations: modules.flatMap((module) => module.settings ?? []),
+  translations, // a key without an English source fails the boot, as does a duplicate id
+  modules, // builds the module toggles, see "System settings"
+});
+const settings = createSettingsService({
+  registry,
+  store, // your SettingsStore adapter, see "Storage adapters"
+  guilds: createDiscordGuildDirectory(client),
+  notifier: createInProcessNotifier(logger),
+  translator,
+  clock: systemClock,
+  logger,
+});
+```
+
+### Reading and writing
+
+Values are typed from the declaration: a required field or a field with a
+default is never `undefined`, a mistyped key fails to compile.
+
+```ts
+const values = await settings.get(tickets, guildId); // cached; defaults for unset fields
+values.maxOpen; // number
+values.staffRole; // string | undefined
+
+const ctx = { guildId, userId, locale }; // who writes, where, in which language
+await settings.validate(tickets, guildId, { maxOpen: 50 }, ctx); // { ok: false, issues: [{ field: "maxOpen", code: "max", ... }] }
+await settings.set(tickets, guildId, { maxOpen: 5, staffRole: null }, ctx); // null unsets a field
+await settings.reset(tickets, guildId, ["maxOpen"], ctx); // or "all"
+const { missing } = await settings.status(tickets, guildId); // required fields left unset
+```
+
+`set` stores nothing unless every submitted field is valid, and throws a
+`SettingsValidationError` listing all the issues. Two writers holding the same
+`expectedRevision` cannot both win: the second gets a `ConflictError`. Every
+write invalidates the cache and emits a `settings.changed` event through the
+notifier. Module logic reads secrets with `get`; surfaces use `getForSurface`,
+where a secret is only `{ isSet }`.
+
+### The Discord settings screen
+
+`settingsEditorFromDeclaration` turns a declaration into the options of
+`mountSettingsEditor`: one control per field kind, groups split into modals of
+at most 5 inputs, nested levels so a card never exceeds Discord's component
+budget, and every save sent through `service.set`, so the screen accepts and
+refuses exactly what the service does.
+
+```ts
+import {
+  editorComponentIds,
+  mountSettingsEditor,
+  settingsEditorFromDeclaration,
+} from "@azurioh/discord-kernel/discord/components/settings-editor";
+
+const adapted = await settingsEditorFromDeclaration(tickets, settings, {
+  guildId,
+  userId,
+  locale: ctx.locale,
+  translator,
+});
+await mountSettingsEditor(ctx.interaction, {
+  ...adapted,
+  ids: editorComponentIds("tickets-settings"),
+  chrome, // your title and colours
+  translator,
+  locale: ctx.locale,
+  clock: systemClock,
+  logger,
+});
+```
+
+### Describing settings for other surfaces
+
+`settings.describe(declaration, locale)` returns a JSON Schema (draft 2020-12)
+with every label and description translated (English for an unsupported
+locale), and kernel hints (kind, group, order, secret) under `x-kernel`. A
+secret's value is never in it. A web dashboard renders its form from this and
+writes through the same `set`.
+
+### Suggestions and strict fields
+
+A field can offer suggestions, static or searched:
+
+```ts
+timezone: field.text({
+  label: "tickets.timezone",
+  suggest: { resolve: searchTimezones, label: timezoneLabel, strict: true },
+}),
+```
+
+`settings.suggest(declaration, key, query, { ...ctx, values })` returns at most
+25 `Choice`s in the command autocomplete's own format, so one search serves
+`/config set` and the settings screen (where a searchable field becomes a
+select). Channel, role and user fields search the guild without any code. A
+search slower than 2.5 s (`SUGGESTION_TIMEOUT_MS`) or failing yields nothing
+and is logged. `settings.label(...)` gives a stored value's readable name. A
+**strict** field accepts only a value its search knows; anything else is an
+`unknownChoice` issue.
+
+### System settings: module toggles and guild language
+
+The kernel declares its own settings like any module (`registry.kernel`): which
+modules are enabled on the guild (`defaultEnabled` on a `BotModule`, `true`
+unless said otherwise) and the bot's language there. Pass a `ModuleGate` to the
+routers and each gated handler is skipped on a guild that disabled its module,
+with a translated reply for commands and components:
+
+```ts
+import { createModuleGate } from "@azurioh/discord-kernel/settings";
+
+const gate = createModuleGate({ service: settings, registry, logger });
+const commands = new CommandRouter({ presenter, logger, translator, gate, localeResolver });
+const components = new ComponentRouter({ presenter, logger, translator, gate, localeResolver });
+const events = new EventRouter(logger, gate);
+commands.registerAll(module.commands ?? [], module.name); // no name: never gated
+```
+
+Scheduled jobs call `gate.isEnabled(moduleName, guildId)` themselves. The guild
+language reaches every reply through the `LocaleResolver` port, described in
+[Per-guild values](#per-guild-values).
+
+### Blocking a command until its module is configured
+
+`requireConfigured(declaration, service)` is a guard for a command or a
+component handler. It denies while a required field is unset, and lets the call
+through as soon as it is set, without a restart. Members with *Manage Server*
+also read which settings are missing.
+
+```ts
+import { requireConfigured } from "@azurioh/discord-kernel/discord/settings/require-configured";
+
+createCommand({ name: "ticket", guard: requireConfigured(tickets, settings), handler });
+```
+
+### Evolving module settings
+
+Adding a field needs nothing: guilds configured before read its default.
+Removing one needs nothing either: its stored value is ignored and dropped on
+the next write. To reshape stored values (rename a key, change a unit), raise
+the declaration's `version` and give it a `migrate`:
+
+```ts
+export const warnings = defineSettings({
+  id: "warnings",
+  version: 2, // was 1: `maxWarnings` became `warnLimit`
+  migrate: (fromVersion, raw) => {
+    if (fromVersion !== 1) throw new Error(`no migration from version ${fromVersion}`);
+    const { maxWarnings, ...rest } = raw as Record<string, unknown>;
+    return maxWarnings === undefined ? rest : { ...rest, warnLimit: maxWarnings };
+  },
+  labels: { title: "warnings.title" },
+  fields: { warnLimit: field.integer({ label: "warnings.limit", min: 1, max: 10, default: 3 }) },
+});
+```
+
+Migration is lazy: the first read of a guild's older record runs `migrate`,
+validates the result like any stored value, and writes it back once under the
+new version (a concurrent reader on another shard loses the compare-and-set and
+simply reads the migrated record). `set` and `reset` migrate first too. Rules for
+`migrate`:
+
+- **Pure.** It receives a copy of the stored values and returns the new ones;
+  no I/O, no clock, no randomness.
+- **Every older version.** A guild may skip releases, so `fromVersion` can be
+  any version below the current one. Chain the steps (v1 → v2 → v3) or throw
+  for a version you no longer support.
+- **Failures are safe.** When it throws or its result fails validation, nothing
+  is written, the error is logged with the guild, module and versions, and the
+  guild reads defaults for the fields it cannot read. A record written by a
+  newer version (after a rollback) is read but never overwritten.
+
+### Storage adapters
+
+Settings persistence is hexagonal: the kernel declares the `SettingsStore` port
+and never imports a database driver. Each database sits behind an adapter your
+bot owns, and the composition root picks one at boot.
+
+```mermaid
+flowchart LR
+    service["SettingsService (kernel)"] --> port(["SettingsStore port"])
+    port -.implemented by.-> memory["createInMemorySettingsStore (kernel, tests)"]
+    port -.implemented by.-> json["JSON file adapter (your bot)"]
+    port -.implemented by.-> sql["SQLite / Postgres adapter (your bot)"]
+    port -.implemented by.-> other["MongoDB / Redis adapter (your bot)"]
+```
+
+The port has three methods: `read`, `write` and `delete`. It stores one
+`StoredSettings` record per `(guildId, moduleId)`, and every field of a record
+is JSON-serialisable. An adapter must honour these guarantees:
+
+| Guarantee | Meaning |
+| --------- | ------- |
+| A missing record reads as `null` | `read` returns `null` until the first write and after a delete |
+| Atomic compare-and-set | `write` lands only if the stored revision equals `expectedRevision` (`null` means no record yet), checked and applied in one atomic step, so of two writers holding the same revision exactly one wins |
+| Conflicts change nothing | A mismatch throws the kernel's `ConflictError` and leaves the stored record as it was. Any other failure is thrown as it is, never as a conflict |
+| Isolation | One `(guildId, moduleId)` never reads, overwrites or deletes another |
+| Idempotent delete | Deleting a missing record succeeds |
+| Independent copies | The store keeps no reference to the record it was given and hands out none it keeps |
+| Faithful round-trip | `read` returns a record equal to the one written (JSON values, `updatedBy` absent stays absent) |
+
+#### Writing an adapter for any database
+
+The only hard part is the compare-and-set. Use the native primitive that checks
+and writes in one step, never a read followed by a write:
+
+- **SQL (Postgres, MySQL, SQLite):** a table keyed `(guild_id, module_id)`. A create
+  is `INSERT ... ON CONFLICT DO NOTHING` and an update is
+  `UPDATE ... WHERE guild_id = ? AND module_id = ? AND revision = ?`. Zero affected
+  rows means `ConflictError`. The sandbox bot's `src/shared/settings/sqlite/` is a
+  worked example.
+- **MongoDB:** one document per key with a unique index on `{ guildId, moduleId }`.
+  An update is `findOneAndUpdate({ guildId, moduleId, revision: expected }, { $set: record })`,
+  where no match means a conflict. A create is `insertOne`, where a duplicate-key error
+  (code 11000) means a conflict.
+- **Redis:** one key per record. Either `WATCH key`, `GET`, compare, then
+  `MULTI`/`SET`/`EXEC`, where a nil `EXEC` means a conflict, or a Lua script that
+  compares the stored revision and sets the key atomically.
+
+Then prove the adapter with the contract suite. It is runner-agnostic: pass it
+your runner's `describe`, `it` and `expect`, and a factory that returns an empty store:
+
+```ts
+// tests/postgres-settings-store.test.ts
+import { runSettingsStoreContract } from "@azurioh/discord-kernel/settings/testing";
+import { afterAll, describe, expect, it } from "vitest";
+import { createPostgresSettingsStore } from "../src/postgres-settings-store";
+import { createTestDatabase } from "./support/test-database";
+
+const database = await createTestDatabase(); // one fresh schema per run
+afterAll(() => database.drop());
+
+runSettingsStoreContract(() => createPostgresSettingsStore(database.freshTable()), { describe, it, expect });
+```
+
+Every guarantee in the table has a case in the suite, including two concurrent
+writers with the same revision. The kernel's own `createInMemorySettingsStore`
+passes the same suite and is the store to use in tests.
+
 ## Making it yours
 
 Two things are global by nature — a bot has one look, decided once — and are set
@@ -58,7 +352,7 @@ from the composition root before any module is constructed:
 
 ```ts
 import { configureEmbedColors } from "@azurioh/discord-kernel/discord/ui/colors";
-import { registerColorAliases } from "@azurioh/discord-kernel/discord/ui/color-input";
+import { registerColorAliases } from "@azurioh/discord-kernel/discord/ui/color-aliases";
 
 configureEmbedColors({ brand: 0xf3c909 });
 registerColorAliases({ gold: "#f3c909", or: "#f3c909" });
@@ -67,6 +361,29 @@ registerColorAliases({ gold: "#f3c909", or: "#f3c909" });
 Everything else is injected: your modules are factories receiving a container
 you define, so nothing in the kernel is reachable as a singleton.
 
+## Per-guild values
+
+A value the kernel uses when it answers an interaction is read through a
+resolver port, per guild, never from a global. The bot passes a default
+implementation built from its own configuration, and any module can replace it
+with its own. Today that value is the reply language:
+
+```ts
+import { createGuildLocaleResolver } from "@azurioh/discord-kernel/discord/settings/guild-locale-resolver";
+
+// Member locale → guild language setting → guild Discord locale → translator default.
+const localeResolver = createGuildLocaleResolver({ service: settings, registry, translator });
+const commands = new CommandRouter({ presenter, logger, translator, localeResolver });
+const components = new ComponentRouter({ presenter, logger, translator, localeResolver });
+```
+
+Any object implementing `LocaleResolver`
+(`@azurioh/discord-kernel/discord/interaction/locale-resolver`) fits:
+`{ resolve({ locale, guildLocale, guildId }) => Promise<Locale> }`. Without one,
+the routers keep the interaction's own locales, so a bot without settings is
+unaffected. A resolver that throws is logged and the interaction's own locales
+are used.
+
 ## Requirements
 
 Node 22.12+, discord.js 14.27+, TypeScript 5.9. The published build is

package/dist/authz/require-level-guard.d.ts

@@ -1,7 +1,7 @@
 import type { BaseInteraction } from "discord.js";
 import type { Authorizer, PermissionLevel } from "../authz/authorizer";
 import type { Guard } from "../discord/command/guard";
-import type { LocalizedText } from "../i18n";
+import type { LocalizedText } from "../i18n/translator";
 /**
  * Role IDs held by the interacting member, resolved without a network call:
  * `interaction.member.roles` is either the cached `GuildMemberRoleManager` (a

package/dist/authz/require-level-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"require-level-guard.d.ts","sourceRoot":"","sources":["../../src/authz/require-level-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,EAAE,CAOpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,aAAa,GACxB,KAAK,CAOP"}
+{"version":3,"file":"require-level-guard.d.ts","sourceRoot":"","sources":["../../src/authz/require-level-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM,EAAE,CAOpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,aAAa,GACxB,KAAK,CAOP"}

package/dist/color.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Discord's own brand colour. Kept with the base names rather than in the
+ * Discord ring so a `blurple` setting means the same colour on every surface,
+ * and so embeds fall back to it when a bot declares no palette.
+ */
+export declare const DISCORD_BLURPLE = "#5865f2";
+/**
+ * Colour names an administrator may type instead of a hex code, French and
+ * English side by side.
+ *
+ * This table is **input vocabulary, not display text**. Nothing in it is ever
+ * shown to anyone, and its keys must never be translated at runtime: a catalog
+ * lookup resolves against the reply locale, which would make `rouge` stop
+ * working the moment an admin's Discord is set to English — the opposite of the
+ * point. Both spellings are accepted from everyone, always, which only a flat
+ * table can promise.
+ *
+ * Fixed on purpose: a value stored from one of these names must mean the same
+ * colour in every bot. Names a bot adds for its own inputs live with those
+ * inputs, not here.
+ */
+export declare const BASE_COLOR_NAMES: Readonly<Record<string, string>>;
+/**
+ * Accents must not be a trap: `dore` and `doré` are the same request, and an
+ * administrator has no way of knowing which one a table happened to spell.
+ * Case and surrounding whitespace are folded for the same reason.
+ */
+export declare function normalizeColorName(raw: string): string;
+/** Index a name → `#rrggbb` table by {@link normalizeColorName}, so lookups fold case and accents. */
+export declare function indexColorNames(names: Readonly<Record<string, string>>): Map<string, string>;
+/**
+ * Normalize a hexadecimal colour code to `#rrggbb`, `null` when the input is
+ * not one. Surrounding whitespace is ignored.
+ */
+export declare function parseHexColor(raw: string): string | null;
+/**
+ * Normalize a colour to `#rrggbb`, from a hexadecimal code or from one of the
+ * {@link BASE_COLOR_NAMES}. `null` for anything else: the refusal belongs to
+ * whichever caller asked, so this only reports that it could not read the value.
+ */
+export declare function parseColor(raw: string): string | null;
+//# sourceMappingURL=color.d.ts.map

package/dist/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../src/color.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAiBzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkC7D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5F;AAQD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErD"}

package/dist/color.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_COLOR_NAMES = exports.DISCORD_BLURPLE = void 0;
+exports.normalizeColorName = normalizeColorName;
+exports.indexColorNames = indexColorNames;
+exports.parseHexColor = parseHexColor;
+exports.parseColor = parseColor;
+/**
+ * The generic web colours, at the value the name carries everywhere else — an
+ * administrator typing `orange` gets the orange they would get in CSS, not a
+ * shade this module invented.
+ */
+const RED = "#ff0000";
+const BLUE = "#0000ff";
+const GREEN = "#008000";
+const YELLOW = "#ffff00";
+const ORANGE = "#ffa500";
+const PURPLE = "#800080";
+const PINK = "#ffc0cb";
+const WHITE = "#ffffff";
+/**
+ * Discord's own brand colour. Kept with the base names rather than in the
+ * Discord ring so a `blurple` setting means the same colour on every surface,
+ * and so embeds fall back to it when a bot declares no palette.
+ */
+exports.DISCORD_BLURPLE = "#5865f2";
+/**
+ * Not `#000000`: Discord reads a zero colour as "no colour set" and renders the
+ * default grey bar instead, so pure black is the one value an administrator
+ * could ask for and never see. One step off zero reads as black.
+ */
+const BLACK = "#010101";
+const GREY = "#808080";
+const CYAN = "#00ffff";
+const BROWN = "#a52a2a";
+const SILVER = "#c0c0c0";
+const TURQUOISE = "#40e0d0";
+const MAGENTA = "#ff00ff";
+const NAVY = "#000080";
+/**
+ * Colour names an administrator may type instead of a hex code, French and
+ * English side by side.
+ *
+ * This table is **input vocabulary, not display text**. Nothing in it is ever
+ * shown to anyone, and its keys must never be translated at runtime: a catalog
+ * lookup resolves against the reply locale, which would make `rouge` stop
+ * working the moment an admin's Discord is set to English — the opposite of the
+ * point. Both spellings are accepted from everyone, always, which only a flat
+ * table can promise.
+ *
+ * Fixed on purpose: a value stored from one of these names must mean the same
+ * colour in every bot. Names a bot adds for its own inputs live with those
+ * inputs, not here.
+ */
+exports.BASE_COLOR_NAMES = {
+    red: RED,
+    rouge: RED,
+    blue: BLUE,
+    bleu: BLUE,
+    green: GREEN,
+    vert: GREEN,
+    yellow: YELLOW,
+    jaune: YELLOW,
+    orange: ORANGE,
+    purple: PURPLE,
+    // French for purple, not the CSS `violet` (a pale pink): an admin typing it
+    // here is asking for the colour the word means in their own language.
+    violet: PURPLE,
+    pink: PINK,
+    rose: PINK,
+    white: WHITE,
+    blanc: WHITE,
+    black: BLACK,
+    noir: BLACK,
+    grey: GREY,
+    gray: GREY,
+    gris: GREY,
+    cyan: CYAN,
+    brown: BROWN,
+    marron: BROWN,
+    silver: SILVER,
+    argent: SILVER,
+    argenté: SILVER,
+    turquoise: TURQUOISE,
+    magenta: MAGENTA,
+    navy: NAVY,
+    marine: NAVY,
+    blurple: exports.DISCORD_BLURPLE,
+};
+/**
+ * Accents must not be a trap: `dore` and `doré` are the same request, and an
+ * administrator has no way of knowing which one a table happened to spell.
+ * Case and surrounding whitespace are folded for the same reason.
+ */
+function normalizeColorName(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/\p{Diacritic}/gu, "");
+}
+/** Index a name → `#rrggbb` table by {@link normalizeColorName}, so lookups fold case and accents. */
+function indexColorNames(names) {
+    return new Map(Object.entries(names).map(([name, hex]) => [normalizeColorName(name), hex]));
+}
+const BASE_COLORS_BY_NORMALIZED_NAME = indexColorNames(exports.BASE_COLOR_NAMES);
+/** `#RGB` and `#RRGGBB`, with or without the leading hash. */
+const HEX_COLOR_PATTERN = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/**
+ * Normalize a hexadecimal colour code to `#rrggbb`, `null` when the input is
+ * not one. Surrounding whitespace is ignored.
+ */
+function parseHexColor(raw) {
+    const value = raw.trim();
+    if (!HEX_COLOR_PATTERN.test(value)) {
+        return null;
+    }
+    const digits = value.replace("#", "").toLowerCase();
+    const expanded = digits.length === 3 ? [...digits].map((digit) => `${digit}${digit}`).join("") : digits;
+    return `#${expanded}`;
+}
+/**
+ * Normalize a colour to `#rrggbb`, from a hexadecimal code or from one of the
+ * {@link BASE_COLOR_NAMES}. `null` for anything else: the refusal belongs to
+ * whichever caller asked, so this only reports that it could not read the value.
+ */
+function parseColor(raw) {
+    return BASE_COLORS_BY_NORMALIZED_NAME.get(normalizeColorName(raw)) ?? parseHexColor(raw);
+}
+//# sourceMappingURL=color.js.map

package/dist/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","sourceRoot":"","sources":["../src/color.ts"],"names":[],"mappings":"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"}

package/dist/discord/command/all-required.d.ts

@@ -0,0 +1,8 @@
+import type { Option, Options } from "../../discord/command/options";
+type AsRequired<O> = O extends Option<infer V, boolean> ? Option<V, true> : never;
+/** Turn every option in a record into its required variant. */
+export declare function allRequired<O extends Options>(fields: O): {
+    [K in keyof O]: AsRequired<O[K]>;
+};
+export {};
+//# sourceMappingURL=all-required.d.ts.map

package/dist/discord/command/all-required.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-required.d.ts","sourceRoot":"","sources":["../../../src/discord/command/all-required.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEjE,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;AAElF,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAM9F"}

package/dist/discord/command/all-required.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allRequired = allRequired;
+/** Turn every option in a record into its required variant. */
+function allRequired(fields) {
+    const out = {};
+    for (const [key, option] of Object.entries(fields)) {
+        out[key] = option.required();
+    }
+    return out;
+}
+//# sourceMappingURL=all-required.js.map

package/dist/discord/command/all-required.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-required.js","sourceRoot":"","sources":["../../../src/discord/command/all-required.ts"],"names":[],"mappings":";;AAKA,kCAMC;AAPD,+DAA+D;AAC/D,SAAgB,WAAW,CAAoB,MAAS;IACvD,MAAM,GAAG,GAAG,EAA0C,CAAC;IACvD,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,GAAc,CAAC,GAAG,MAAM,CAAC,QAAQ,EAA4B,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/discord/command/autocomplete-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocomplete-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,qBAAqB;IAElE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM;IAGhC,+DAA+D;IACzD,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA0BxD"}
+{"version":3,"file":"autocomplete-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,qBAAqB;IAElE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM;IAGhC,+DAA+D;IACzD,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CA0BxD"}

package/dist/discord/command/autocomplete-dispatcher.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutocompleteDispatcher = void 0;
+const error_message_1 = require("../../errors/error-message");
 /**
  * Answers option autocomplete requests. It is an {@link InteractionDispatcher}
  * aggregated by the shared {@link InteractionRouter}, never a second
@@ -31,7 +32,7 @@ class AutocompleteDispatcher {
         catch (error) {
             this.logger.error({
                 command: interaction.commandName,
-                err: error instanceof Error ? error.message : String(error),
+                err: (0, error_message_1.errorMessage)(error),
             }, "Autocomplete handler failed");
         }
         return true;

package/dist/discord/command/autocomplete-dispatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"autocomplete-dispatcher.js","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":";;;AAeA;;;;GAIG;AACH,MAAa,sBAAsB;IAEhB;IACA;IAFlB,YACkB,QAAuB,EACvB,MAAc;QADd,aAAQ,GAAR,QAAQ,CAAe;QACvB,WAAM,GAAN,MAAM,CAAQ;IAC7B,CAAC;IAEJ,+DAA+D;IAC/D,KAAK,CAAC,MAAM,CAAC,WAAwB;QACpC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACd,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,mEAAmE;QACnE,IAAI,CAAC;YACJ,MAAM,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAChB;gBACC,OAAO,EAAE,WAAW,CAAC,WAAW;gBAChC,GAAG,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC3D,EACD,6BAA6B,CAC7B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AAjCD,wDAiCC"}
+{"version":3,"file":"autocomplete-dispatcher.js","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-dispatcher.ts"],"names":[],"mappings":";;;AAGA,0DAAsD;AAatD;;;;GAIG;AACH,MAAa,sBAAsB;IAEhB;IACA;IAFlB,YACkB,QAAuB,EACvB,MAAc;QADd,aAAQ,GAAR,QAAQ,CAAe;QACvB,WAAM,GAAN,MAAM,CAAQ;IAC7B,CAAC;IAEJ,+DAA+D;IAC/D,KAAK,CAAC,MAAM,CAAC,WAAwB;QACpC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACd,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,mEAAmE;QACnE,IAAI,CAAC;YACJ,MAAM,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAChB;gBACC,OAAO,EAAE,WAAW,CAAC,WAAW;gBAChC,GAAG,EAAE,IAAA,4BAAY,EAAC,KAAK,CAAC;aACxB,EACD,6BAA6B,CAC7B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AAjCD,wDAiCC"}

package/dist/discord/command/autocomplete-limits.d.ts

@@ -0,0 +1,3 @@
+/** Discord refuses an autocomplete response carrying more than this many choices. */
+export declare const MAX_AUTOCOMPLETE_CHOICES = 25;
+//# sourceMappingURL=autocomplete-limits.d.ts.map

package/dist/discord/command/autocomplete-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete-limits.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-limits.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,KAAK,CAAC"}

package/dist/discord/command/autocomplete-limits.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_AUTOCOMPLETE_CHOICES = void 0;
+/** Discord refuses an autocomplete response carrying more than this many choices. */
+exports.MAX_AUTOCOMPLETE_CHOICES = 25;
+//# sourceMappingURL=autocomplete-limits.js.map

package/dist/discord/command/autocomplete-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete-limits.js","sourceRoot":"","sources":["../../../src/discord/command/autocomplete-limits.ts"],"names":[],"mappings":";;;AAAA,qFAAqF;AACxE,QAAA,wBAAwB,GAAG,EAAE,CAAC"}

package/dist/discord/command/autocomplete.d.ts

@@ -1,6 +1,11 @@
 import type { AutocompleteInteraction } from "discord.js";
-import { type CompiledSubcommand } from "../../discord/command/create-command";
+import type { CompiledSubcommand } from "../../discord/command/create-command";
 import type { Options } from "../../discord/command/options";
+/**
+ * Serving option autocomplete. Kept beside the DSL because resolving *which*
+ * option is focused needs the same route table `createCommand` builds — the
+ * dispatcher only decides that an interaction is an autocomplete request.
+ */
 /**
  * Answer a focused option's autocomplete request.
  *

package/dist/discord/command/autocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,KAAK,kBAAkB,EAAY,MAAM,kCAAkC,CAAC;AACrF,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAWjE;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,WAAW,EAAE,uBAAuB,EACpC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAsBf;AAWD;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,uBAAuB,EACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACvC,WAAW,EAAE,OAAO,GAAG,IAAI,GACzB,OAAO,CAUT"}
+{"version":3,"file":"autocomplete.d.ts","sourceRoot":"","sources":["../../../src/discord/command/autocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIzD;;;;GAIG;AAEH;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,WAAW,EAAE,uBAAuB,EACpC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAsBf;AAYD;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,uBAAuB,EACpC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACvC,WAAW,EAAE,OAAO,GAAG,IAAI,GACzB,OAAO,CAUT"}