@helyx/bot 0.4.37 → 0.4.38

package/dist/command-sync.d.ts

@@ -1,4 +1,5 @@
 import type { ModuleDefinition } from "@helyx/sdk";
+import type { GlobalCommandRegistrationMode } from "./command-registration-policy.js";
 export interface CommandHashState {
     value: unknown;
     version: bigint;
@@ -8,13 +9,14 @@ export interface CommandHashStore {
     set(key: string, value: unknown, expectedVersion?: bigint | null): Promise<CommandHashState>;
 }
 export interface DiscordCommandRest {
+    get?(route: `/${string}`): Promise<unknown>;
     put(route: `/${string}`, options: {
         body: unknown;
     }): Promise<unknown>;
 }
 export interface CommandSyncResult {
     global: "updated" | "unchanged";
-    guild: "updated" | "unchanged" | "not_configured";
+    guild: "updated" | "unchanged" | "not_configured" | "delegated";
     globalCount: number;
     guildCount: number;
     globalHash: string;
@@ -24,7 +26,9 @@ export declare function synchroniseApplicationCommands(input: {
     applicationId: string;
     token: string;
     modules: readonly ModuleDefinition[];
+    globalCommandMode?: GlobalCommandRegistrationMode;
     internalGuildId?: string;
+    synchroniseInternalGuild?: boolean;
     state: CommandHashStore;
     rest?: DiscordCommandRest;
 }): Promise<CommandSyncResult>;

package/dist/command-sync.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { REST, Routes } from "discord.js";
 import { buildApplicationCommandDefinitions } from "./interactions.js";
 export async function synchroniseApplicationCommands(input) {
-    const definitions = buildApplicationCommandDefinitions(input.modules, input.internalGuildId);
+    const definitions = buildApplicationCommandDefinitions(input.modules, input.internalGuildId, input.globalCommandMode);
     definitions.global.sort((left, right) => left.name.localeCompare(right.name));
     definitions.guild.sort((left, right) => left.name.localeCompare(right.name));
     const rest = input.rest ?? new REST({ version: "10" }).setToken(input.token);
@@ -13,6 +13,7 @@ export async function synchroniseApplicationCommands(input) {
         hash: globalHash,
         definitions: definitions.global,
         state: input.state,
+        observe: () => rest.get?.(Routes.applicationCommands(input.applicationId)),
         update: () => rest.put(Routes.applicationCommands(input.applicationId), {
             body: definitions.global,
         }),
@@ -25,6 +26,15 @@ export async function synchroniseApplicationCommands(input) {
             guildCount: 0,
             globalHash,
         };
+    if (input.synchroniseInternalGuild === false)
+        return {
+            global,
+            guild: "delegated",
+            globalCount: definitions.global.length,
+            guildCount: definitions.guild.length,
+            globalHash,
+            guildHash: commandDefinitionsHash(definitions.guild),
+        };
     const guildKey = `commands:${input.applicationId}:guild:${input.internalGuildId}`;
     const guildHash = commandDefinitionsHash(definitions.guild);
     const guild = await synchroniseCollection({
@@ -32,6 +42,7 @@ export async function synchroniseApplicationCommands(input) {
         hash: guildHash,
         definitions: definitions.guild,
         state: input.state,
+        observe: () => rest.get?.(Routes.applicationGuildCommands(input.applicationId, input.internalGuildId)),
         update: () => rest.put(Routes.applicationGuildCommands(input.applicationId, input.internalGuildId), { body: definitions.guild }),
     });
     return {
@@ -48,8 +59,13 @@ export function commandDefinitionsHash(definitions) {
 }
 async function synchroniseCollection(input) {
     const current = await input.state.get(input.key);
-    if (isCommandHashState(current?.value, input.hash))
-        return "unchanged";
+    if (isCommandHashState(current?.value, input.hash)) {
+        const observed = input.observe();
+        if (observed &&
+            commandDefinitionsHash(normalizeObservedCommands(await observed)) ===
+                commandDefinitionsHash(normalizeDesiredCommands(input.definitions)))
+            return "unchanged";
+    }
     await input.update();
     await input.state.set(input.key, {
         hash: input.hash,
@@ -58,6 +74,54 @@ async function synchroniseCollection(input) {
     }, current?.version ?? null);
     return "updated";
 }
+function normalizeObservedCommands(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((command) => normalizeDiscordCommand(command))
+        .sort((left, right) => commandName(left).localeCompare(commandName(right)));
+}
+function normalizeDesiredCommands(value) {
+    return value
+        .map((command) => normalizeDiscordCommand(command))
+        .sort((left, right) => commandName(left).localeCompare(commandName(right)));
+}
+function normalizeDiscordCommand(value, root = true) {
+    if (Array.isArray(value))
+        return value.map((item) => normalizeDiscordCommand(item, false));
+    if (!value || typeof value !== "object")
+        return value;
+    const ignored = new Set(["id", "application_id", "guild_id", "version"]);
+    const result = Object.fromEntries(Object.entries(value)
+        .filter(([key, nested]) => {
+        if (ignored.has(key) || nested === undefined)
+            return false;
+        if (key === "nsfw" && nested === false)
+            return false;
+        if (key === "default_permission" && nested === true)
+            return false;
+        if (key === "default_member_permissions" && nested === null)
+            return false;
+        if (key === "required" && nested === false)
+            return false;
+        if (key.endsWith("_localizations") && nested === null)
+            return false;
+        if (key === "options" && Array.isArray(nested) && nested.length === 0)
+            return false;
+        return true;
+    })
+        .map(([key, nested]) => [key, normalizeDiscordCommand(nested, false)]));
+    if (root) {
+        result.contexts ??= [0];
+        result.integration_types ??= [0];
+    }
+    return result;
+}
+function commandName(value) {
+    return value && typeof value === "object" && "name" in value
+        ? String(value.name)
+        : "";
+}
 function isCommandHashState(value, expectedHash) {
     return (typeof value === "object" &&
         value !== null &&

package/dist/control-server.d.ts

@@ -3,10 +3,13 @@ import { type DashboardActionResult, type GuildAccessPolicy, type ManagedResourc
 import { type ActionReceipt, type SignedAssessmentEnvelope } from "@helyx/verification-contracts";
 import { type Client } from "discord.js";
 import { type FastifyInstance } from "fastify";
+import { type BotModuleStatusMutationResult } from "./module-status-control.js";
+import { type FirstTimeCommandSetupHandler } from "./first-time-command-setup.js";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
 import { type DashboardPermissionState } from "./control-permissions.js";
 import { type DashboardCommandDefinition } from "./dashboard-commands.js";
 import { type AvailabilityModuleCatalogue } from "./module-availability-control.js";
+import { registerGuildCommandControlRoutes } from "./guild-command-control-routes.js";
 interface DashboardLogEventDefinition {
     id: string;
     name: string;
@@ -139,7 +142,7 @@ export interface DashboardGuildAccessState extends GuildAccessPolicy {
     actorHighestRolePosition: number | null;
     updatedAt: string | null;
 }
-export interface BotControlHandler {
+export interface BotControlHandler extends FirstTimeCommandSetupHandler {
     cleanupOAuthConsumer(input: {
         consumerBindingId: string;
         moduleId: string;
@@ -193,7 +196,7 @@ export interface BotControlHandler {
         enabled: boolean;
         actorUserId: string;
         correlationId: string;
-    }): Promise<BotControlState>;
+    }): Promise<BotModuleStatusMutationResult>;
     updateConfiguration(input: {
         guildId: string;
         moduleId: string;
@@ -422,7 +425,15 @@ export declare class BotControlService implements BotControlHandler {
         enabled: boolean;
         actorUserId: string;
         correlationId: string;
-    }): Promise<BotControlState>;
+    }): Promise<BotModuleStatusMutationResult>;
+    completeFirstTimeCommandSetup(input: {
+        guildId: string;
+        moduleIds: string[];
+        expectedRevision: bigint;
+        idempotencyKey: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<BotModuleStatusMutationResult>;
     updateConfiguration(input: {
         guildId: string;
         moduleId: string;
@@ -548,6 +559,7 @@ export declare function createBotControlServer(input: {
         level: string;
     };
     shardHealth?: () => Promise<ShardHealthSnapshot>;
+    guildCommands?: Parameters<typeof registerGuildCommandControlRoutes>[1];
 }): Promise<FastifyInstance>;
 export declare function mapBotControlError(error: unknown): {
     status: 400 | 403 | 404 | 409;

package/dist/control-server.js

@@ -1,4 +1,4 @@
-import { AuditRepository, GuildAccessPolicyRepository, InstallationRepository, ModuleLoggingPolicyRepository, OptimisticConcurrencyError, PermissionPolicyRepository, withTransaction, } from "@helyx/database";
+import { AuditRepository, GuildAccessPolicyRepository, GuildCommandActiveLeaseError, GuildCommandRevisionConflictError, GuildCommandSetupConflictError, InstallationRepository, ModuleLoggingPolicyRepository, OptimisticConcurrencyError, PermissionPolicyRepository, withTransaction, } from "@helyx/database";
 import { DashboardActionValidationError, DEFAULT_GUILD_ACCESS_POLICY, HELYX_SERVICE_NAMES, ModuleStateValidationError, } from "@helyx/sdk";
 import { actionReceiptSchema, signedAssessmentEnvelopeSchema, } from "@helyx/verification-contracts";
 import { canAccessGuildDashboard, canMutatePermissionPolicy, canUseCommand, permissionMutationDenialMessage, resolveHelyxAuthority, } from "@helyx/core";
@@ -7,12 +7,14 @@ import Fastify, {} from "fastify";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { z, ZodError } from "zod";
 import { addChannelMessageReaction as addDiscordChannelMessageReaction, deleteChannelMessage as deleteDiscordChannelMessage, editChannelMessage as editDiscordChannelMessage, normalizeDiscordPermission, sendToChannel as sendDiscordMessageToChannel, } from "./interactions.js";
-import { runNestedGuildBarriers } from "./numeric-barriers.js";
+import { mutateDashboardModuleStatus, } from "./module-status-control.js";
+import { completeFirstTimeCommandSetup, } from "./first-time-command-setup.js";
 import { SHARD_HEALTH_STALE_MS, } from "./shard-contracts.js";
 import { dashboardCategoryLabel } from "./dashboard-category.js";
 import { assertVersion, dashboardActionPermissionId, declaredManagedResourcePermission, fromDashboardPolicy, managedResourcePermissionId, permissionPoliciesEqual, permissionPolicyKey, safeOptionalVersion, safeVersion, toDashboardPolicy, } from "./control-permissions.js";
 import { dashboardCommands, } from "./dashboard-commands.js";
 import { availabilityCatalogueDefinitions, availabilityCatalogue, dashboardModuleStatus, disabledModuleSummary, moduleAvailabilityService, moduleAvailabilityStates, } from "./module-availability-control.js";
+import { registerGuildCommandControlRoutes } from "./guild-command-control-routes.js";
 const snowflake = z.string().regex(/^\d{17,20}$/u);
 const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
 const MAX_DISCORD_SETTING_SELECTIONS = 25;
@@ -628,53 +630,21 @@ export class BotControlService {
     }
     async setModuleStatus(input) {
         const module = this.#requireDashboardModule(input.moduleId);
-        await this.#requireModuleAvailable(input.moduleId);
-        const scopes = Object.entries(module.records ?? {})
-            .filter(([, collection]) => (collection.incrementableFields?.length ?? 0) > 0)
-            .map(([collection]) => ({
-            moduleId: input.moduleId,
-            collection,
-            guildId: input.guildId,
-        }));
-        const writeBehind = scopes.length > 0 &&
-            this.#services.has(HELYX_SERVICE_NAMES.numericWriteBehind)
-            ? this.#services.get(HELYX_SERVICE_NAMES.numericWriteBehind)
-            : null;
-        const setEnabled = () => this.#installations.setModuleEnabled({
-            guildId: input.guildId,
-            moduleId: input.moduleId,
-            enabled: input.enabled,
-            context: {
-                actorUserId: input.actorUserId,
-                correlationId: input.correlationId,
-                source: "dashboard",
-            },
+        return mutateDashboardModuleStatus({
+            change: input,
+            module,
+            dashboardModuleIds: this.#dashboardModules.map(({ id }) => id),
+            installations: this.#installations,
+            services: this.#services,
+            requireModuleAvailable: () => this.#requireModuleAvailable(input.moduleId),
+        });
+    }
+    async completeFirstTimeCommandSetup(input) {
+        return completeFirstTimeCommandSetup({
+            installations: this.#installations,
+            dashboardModuleIds: this.#dashboardModules.map(({ id }) => id),
+            change: input,
         });
-        if (!writeBehind) {
-            await setEnabled();
-        }
-        else if (input.enabled) {
-            for (const scope of scopes) {
-                const suppression = await writeBehind.suppressGuild(scope);
-                await writeBehind.releaseGuild({
-                    ...scope,
-                    suppressionId: suppression.suppressionId,
-                });
-            }
-            await setEnabled();
-        }
-        else {
-            await runNestedGuildBarriers({
-                scopes,
-                writeBehind,
-                operation: setEnabled,
-            });
-            for (const scope of scopes)
-                await writeBehind.flushGuild(scope);
-            for (const scope of scopes)
-                await writeBehind.suppressGuild(scope);
-        }
-        return this.getGuildState(input.guildId);
     }
     async updateConfiguration(input) {
         const module = this.#requireDashboardModule(input.moduleId);
@@ -1253,6 +1223,7 @@ export async function createBotControlServer(input) {
     }
     server.get("/health", (_request, reply) => readiness(reply));
     server.get("/v1/health", (_request, reply) => readiness(reply));
+    registerGuildCommandControlRoutes(server, input.guildCommands, input.service);
     server.post("/v1/verification/results", async (request) => input.service.acceptVerificationResult(signedAssessmentEnvelopeSchema.parse(request.body)));
     server.post("/v1/oauth/consumers/cleanup", async (request) => {
         const body = z
@@ -1747,6 +1718,21 @@ export function mapBotControlError(error) {
             status: 409,
             message: "Configuration changed in another session. Reload and try again.",
         };
+    if (error instanceof GuildCommandRevisionConflictError)
+        return {
+            status: 409,
+            message: "Command state changed in another session. Refresh and try again.",
+        };
+    if (error instanceof GuildCommandActiveLeaseError)
+        return {
+            status: 409,
+            message: "A command build is already running. Wait for it to finish.",
+        };
+    if (error instanceof GuildCommandSetupConflictError)
+        return {
+            status: 409,
+            message: "Command setup changed. Reload the page and try again.",
+        };
     return undefined;
 }
 class BotControlValidationError extends Error {

package/dist/dashboard-commands.js

@@ -27,7 +27,11 @@ export function dashboardCommands(module) {
             }),
         ];
     });
-    commands.push(...(module.nexusCommands ?? []).map((command) => dashboardCommand(module, {
+    commands.push(...(module.sharedCommands ?? []).map((command) => dashboardCommand(module, {
+        id: command.permissionId ?? `${command.family}.${command.path}`,
+        name: `/${command.family} ${command.path.replace(".", " ")}`,
+        description: command.description,
+    })), ...(module.nexusCommands ?? []).map((command) => dashboardCommand(module, {
         id: `nexus.${command.path}`,
         name: `/nexus ${command.path.replace(".", " ")}`,
         description: command.description,

package/dist/developer-operations-module.d.ts

@@ -1,5 +1,6 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
+import type { TriviaDataProvider } from "./trivia-data-provider.js";
 export interface ShardHealthProvider {
     getHealth(): Promise<ShardHealthSnapshot>;
 }
@@ -17,6 +18,7 @@ export interface DeveloperOperationsInput {
     modules: readonly DeveloperModuleSummary[];
     processLabel: string;
     health: ShardHealthProvider;
+    triviaData: TriviaDataProvider;
 }
 export declare function createDeveloperOperationsModule(input: DeveloperOperationsInput): ModuleDefinition;
 export declare class WorkerShardHealthProvider implements ShardHealthProvider {

package/dist/developer-operations-module.js

@@ -35,6 +35,7 @@ export function createDeveloperOperationsModule(input) {
                             name: "shards",
                             description: "Show bounded read-only shard health",
                             acknowledgement: "deferred-ephemeral",
+                            authorization: "self-authorized",
                             rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
                             async execute(context) {
                                 if (!(await authorizeDeveloperCommand(context)))
@@ -83,8 +84,8 @@ export function createDeveloperOperationsModule(input) {
                         {
                             name: "bot",
                             description: "Show the bot build and installed module versions",
-                            acknowledgement: "deferred-ephemeral",
-                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            acknowledgement: "immediate-response",
+                            authorization: "self-authorized",
                             async execute(context) {
                                 if (!(await authorizeDeveloperCommand(context)))
                                     return;
@@ -137,8 +138,8 @@ export function createDeveloperOperationsModule(input) {
                         {
                             name: "proc",
                             description: "Show safe process resource and uptime information",
-                            acknowledgement: "deferred-ephemeral",
-                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            acknowledgement: "immediate-response",
+                            authorization: "self-authorized",
                             async execute(context) {
                                 if (!(await authorizeDeveloperCommand(context)))
                                     return;
@@ -168,6 +169,57 @@ export function createDeveloperOperationsModule(input) {
                                 });
                             },
                         },
+                        {
+                            name: "trivia-data",
+                            description: "Show question counts from the Trivia database",
+                            acknowledgement: "deferred-ephemeral",
+                            authorization: "self-authorized",
+                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await authorizeDeveloperCommand(context)))
+                                    return;
+                                let summary;
+                                try {
+                                    summary = await input.triviaData.getSummary();
+                                }
+                                catch {
+                                    await context.reply({
+                                        ephemeral: true,
+                                        componentsV2: {
+                                            accentColor: 0xdc2626,
+                                            text: [
+                                                {
+                                                    content: "Trivia data is unavailable. Check the bot database connection and Trivia migrations.",
+                                                },
+                                            ],
+                                        },
+                                    });
+                                    return;
+                                }
+                                const categoryLines = summary.categories.map((entry) => {
+                                    const total = entry.easy + entry.medium + entry.hard;
+                                    return `**${categoryLabel(entry.category)}**: Easy ${entry.easy.toLocaleString("en-GB")} | Medium ${entry.medium.toLocaleString("en-GB")} | Hard ${entry.hard.toLocaleString("en-GB")} | Total ${total.toLocaleString("en-GB")}`;
+                                });
+                                await context.reply({
+                                    ephemeral: true,
+                                    componentsV2: {
+                                        accentColor: 0x2563eb,
+                                        text: [
+                                            {
+                                                content: [
+                                                    "## Trivia data",
+                                                    `**Unique questions:** ${summary.uniqueQuestions.toLocaleString("en-GB")}`,
+                                                    `**Multiple Choice:** ${summary.types.multipleChoice.toLocaleString("en-GB")} | **Guess:** ${summary.types.guess.toLocaleString("en-GB")} | **True or False:** ${summary.types.trueFalse.toLocaleString("en-GB")}`,
+                                                    "",
+                                                    "### Questions by category",
+                                                    ...categoryLines,
+                                                ].join("\n"),
+                                            },
+                                        ],
+                                    },
+                                });
+                            },
+                        },
                     ],
                 },
             ],
@@ -198,6 +250,15 @@ export function createDeveloperOperationsModule(input) {
 function safeInlineCode(value) {
     return `\`${value.replaceAll("`", "'").slice(0, 120)}\``;
 }
+function categoryLabel(category) {
+    if (category === "science")
+        return "Science and Nature";
+    return category
+        .split("_")
+        .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
+        .join(" ")
+        .replace("And", "and");
+}
 function formatBytes(value) {
     return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
 }

package/dist/discord-rest.d.ts

@@ -0,0 +1,5 @@
+import { Agent } from "undici";
+export declare const discordRestOptions: {
+    readonly agent: Agent;
+};
+//# sourceMappingURL=discord-rest.d.ts.map

package/dist/discord-rest.js

@@ -0,0 +1,9 @@
+import { Agent } from "undici";
+const discordRestAgent = new Agent({
+    keepAliveTimeout: 60_000,
+    keepAliveMaxTimeout: 120_000,
+    connections: 10,
+    pipelining: 1,
+});
+export const discordRestOptions = { agent: discordRestAgent };
+//# sourceMappingURL=discord-rest.js.map

package/dist/events.js

@@ -1002,10 +1002,12 @@ export class DiscordMessageDeliveryService {
     async send(input) {
         validateSnowflake(input.guildId, "guild");
         validateSnowflake(input.channelId, "channel");
-        const guild = await this.client.guilds.fetch(input.guildId);
+        const guild = this.client.guilds.cache.get(input.guildId) ??
+            (await this.client.guilds.fetch(input.guildId));
         if (guild.id !== input.guildId)
             throw new Error("Discord guild validation failed");
-        const channel = await guild.channels.fetch(input.channelId);
+        const channel = guild.channels.cache.get(input.channelId) ??
+            (await guild.channels.fetch(input.channelId));
         if (!channel ||
             channel.guild.id !== guild.id ||
             !channel.isSendable() ||

package/dist/first-time-command-setup.d.ts

@@ -0,0 +1,25 @@
+import type { InstallationService } from "@helyx/sdk";
+import type { BotModuleStatusMutationResult } from "./module-status-control.js";
+export interface FirstTimeCommandSetupHandler {
+    completeFirstTimeCommandSetup(input: {
+        guildId: string;
+        moduleIds: string[];
+        expectedRevision: bigint;
+        idempotencyKey: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<BotModuleStatusMutationResult>;
+}
+export declare function completeFirstTimeCommandSetup(input: {
+    installations: InstallationService;
+    dashboardModuleIds: readonly string[];
+    change: {
+        guildId: string;
+        moduleIds: string[];
+        expectedRevision: bigint;
+        idempotencyKey: string;
+        actorUserId: string;
+        correlationId: string;
+    };
+}): Promise<BotModuleStatusMutationResult>;
+//# sourceMappingURL=first-time-command-setup.d.ts.map

package/dist/first-time-command-setup.js

@@ -0,0 +1,22 @@
+export async function completeFirstTimeCommandSetup(input) {
+    if (!input.installations.completeFirstTimeSetup)
+        throw new Error("First-time setup is unavailable");
+    const result = await input.installations.completeFirstTimeSetup({
+        guildId: input.change.guildId,
+        moduleIds: input.change.moduleIds,
+        expectedRevision: input.change.expectedRevision,
+        idempotencyKey: input.change.idempotencyKey,
+        context: {
+            actorUserId: input.change.actorUserId,
+            correlationId: input.change.correlationId,
+            source: "dashboard",
+        },
+    });
+    const dashboardModuleIds = new Set(input.dashboardModuleIds);
+    return {
+        moduleStatuses: Object.fromEntries(result.transitionedModuleIds
+            .filter((moduleId) => dashboardModuleIds.has(moduleId))
+            .map((moduleId) => [moduleId, "enabled"])),
+    };
+}
+//# sourceMappingURL=first-time-command-setup.js.map

package/dist/guild-command-control-routes.d.ts

@@ -0,0 +1,5 @@
+import type { FastifyInstance } from "fastify";
+import type { GuildCommandReadHandler } from "./guild-command-read-service.js";
+import type { BotControlHandler } from "./control-server.js";
+export declare function registerGuildCommandControlRoutes(server: FastifyInstance, commands: GuildCommandReadHandler | undefined, setup: Pick<BotControlHandler, "completeFirstTimeCommandSetup">): void;
+//# sourceMappingURL=guild-command-control-routes.d.ts.map