@helyx/bot 0.4.33 → 0.4.35

package/dist/interactions.d.ts

@@ -1,5 +1,6 @@
 import type { CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
 import { ModalBuilder, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+export declare const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
 export interface InteractionLogger {
     info(fields: Record<string, unknown>, message: string): void;
     warn(fields: Record<string, unknown>, message: string): void;
@@ -16,7 +17,7 @@ export declare function buildApplicationCommandDefinitions(modules: readonly Mod
     global: ReturnType<typeof toCommandDefinition>[];
     guild: ReturnType<typeof toCommandDefinition>[];
 };
-export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null): CommandContribution["execute"];
+export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null, groupName?: string | null): CommandContribution["execute"];
 export declare function toCommandDefinition(registered: {
     contribution: CommandContribution;
 }): import("discord.js").RESTPostAPIChatInputApplicationCommandsJSONBody;
@@ -27,7 +28,7 @@ export declare function sendToChannel(client: Client, channelId: string, respons
 export declare function deleteChannelMessage(client: Client, channelId: string, messageId: string): Promise<void>;
 export declare function editChannelMessage(client: Client, channelId: string, messageId: string, response: MessageResponse): Promise<void>;
 export declare function addChannelMessageReaction(client: Client, channelId: string, messageId: string, emojiIdentifier: string): Promise<void>;
-export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean): Promise<boolean>;
+export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean, requiredModuleName?: string): Promise<boolean>;
 export declare function normalizeDiscordPermission(permission: string): string;
 export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
 export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;

package/dist/interactions.js

@@ -1,6 +1,7 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { canUseCommand } from "@helyx/core";
 import { ActionRowBuilder, ButtonBuilder, ButtonStyle, ChannelSelectMenuBuilder, EmbedBuilder, Events, GuildMember, ApplicationIntegrationType, ChannelType, InteractionContextType, LabelBuilder, MessageFlags, MentionableSelectMenuBuilder, ModalBuilder, RoleSelectMenuBuilder, StringSelectMenuBuilder, SlashCommandBuilder, TextInputBuilder, TextInputStyle, UserSelectMenuBuilder, TextDisplayBuilder, PermissionFlagsBits, escapeMarkdown, } from "discord.js";
+import { collectCommandRegistrations, } from "./nexus-commands.js";
 const buttonStyles = {
     primary: ButtonStyle.Primary,
     secondary: ButtonStyle.Secondary,
@@ -8,11 +9,18 @@ const buttonStyles = {
     danger: ButtonStyle.Danger,
     link: ButtonStyle.Link,
 };
+export const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
+async function moduleIsGloballyAvailable(services, moduleId) {
+    if (typeof services.has !== "function" ||
+        !services.has(HELYX_SERVICE_NAMES.moduleAvailability))
+        return true;
+    const availability = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
+    return typeof availability?.isAvailable !== "function"
+        ? true
+        : availability.isAvailable(moduleId);
+}
 export function installInteractions(client, modules, registration, logger, services) {
-    const commands = uniqueMap(modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        contribution,
-    }))), ({ contribution }) => contribution.name, "command name");
+    const commands = collectCommandRegistrations(modules);
     const globalCommands = [...commands.values()].filter(({ contribution }) => contribution.registration === "global");
     const guildCommands = [...commands.values()].filter(({ contribution }) => contribution.registration === "guild");
     if (guildCommands.length > 0 && !registration.internalGuildId) {
@@ -74,16 +82,20 @@ export function installInteractions(client, modules, registration, logger, servi
         try {
             if (interaction.isAutocomplete()) {
                 const registered = commands.get(interaction.commandName);
-                const subcommandName = registered?.contribution.subcommands?.length
+                const groupName = registered?.contribution.subcommandGroups?.length
+                    ? interaction.options.getSubcommandGroup(false)
+                    : null;
+                const subcommandName = hasNestedCommands(registered?.contribution)
                     ? interaction.options.getSubcommand(false)
                     : null;
-                const subcommand = subcommandName
-                    ? registered?.contribution.subcommands?.find(({ name }) => name === subcommandName)
-                    : undefined;
+                const subcommand = resolveCommandSubcommand(registered?.contribution, subcommandName, groupName);
+                const owner = resolveCommandOwner(registered, subcommandName, groupName);
                 if (!registered ||
                     !subcommand?.autocomplete ||
-                    !(await authorizeAutocomplete(interaction, registered.moduleId, subcommand.permissionId ??
-                        `${registered.contribution.name}.${subcommand.name}`, services, registration.selfAuthorizingGuildModuleIds?.has(registered.moduleId) ?? false, subcommand.authorization === "resource-scoped"))) {
+                    !(await authorizeAutocomplete(interaction, owner?.moduleId ?? registered.moduleId, subcommand.permissionId ??
+                        [registered.contribution.name, groupName, subcommand.name]
+                            .filter(Boolean)
+                            .join("."), services, registration.selfAuthorizingGuildModuleIds?.has(owner?.moduleId ?? registered.moduleId) ?? false, subcommand.authorization === "resource-scoped"))) {
                     await interaction.respond([]);
                     return;
                 }
@@ -91,24 +103,35 @@ export function installInteractions(client, modules, registration, logger, servi
             }
             else if (interaction.isChatInputCommand()) {
                 const registered = commands.get(interaction.commandName);
-                if (registered) {
+                if (!registered) {
+                    logger.warn({
+                        event: "interaction.stale_command",
+                        commandName: interaction.commandName,
+                    }, "Interaction used a command that is no longer loaded");
+                    await interaction.reply({
+                        content: "This command is no longer available. Refresh Discord and try again.",
+                        flags: MessageFlags.Ephemeral,
+                    });
+                    return;
+                }
+                {
                     const { contribution: command, moduleId } = registered;
-                    const subcommandName = command.subcommands?.length
+                    const groupName = command.subcommandGroups?.length
+                        ? interaction.options.getSubcommandGroup(false)
+                        : null;
+                    const subcommandName = hasNestedCommands(command)
                         ? interaction.options.getSubcommand(false)
                         : null;
-                    const subcommand = subcommandName
-                        ? command.subcommands?.find(({ name }) => name === subcommandName)
-                        : undefined;
-                    const execute = resolveCommandExecutor(command, subcommandName);
+                    const subcommand = resolveCommandSubcommand(command, subcommandName, groupName);
+                    const execute = resolveCommandExecutor(command, subcommandName, groupName);
                     if (!execute) {
                         logger.warn({
                             event: "interaction.stale_command",
                             commandName: command.name,
                             ...(subcommandName ? { subcommandName } : {}),
+                            ...(groupName ? { groupName } : {}),
                         }, "Interaction used an outdated command definition");
-                        const choices = (command.subcommands ?? [])
-                            .map(({ name }) => `\`/${command.name} ${name}\``)
-                            .join(" or ");
+                        const choices = commandChoices(command).join(" or ");
                         await interaction.reply({
                             content: choices
                                 ? `This command was recently updated. Refresh Discord, then use ${choices}.`
@@ -118,11 +141,19 @@ export function installInteractions(client, modules, registration, logger, servi
                         return;
                     }
                     const commandId = subcommandName
-                        ? `${command.name}.${subcommandName}`
+                        ? [command.name, groupName, subcommandName]
+                            .filter(Boolean)
+                            .join(".")
                         : command.name;
                     const permissionId = subcommand?.permissionId ?? command.permissionId ?? commandId;
-                    if (await authorizeCommand(interaction, moduleId, permissionId, subcommand?.rateLimit ?? command.rateLimit, services, registration.selfAuthorizingGuildModuleIds?.has(moduleId) ??
-                        false, subcommand?.authorization === "resource-scoped")) {
+                    const owner = resolveCommandOwner(registered, subcommandName, groupName);
+                    const ownerModuleId = owner?.moduleId ?? moduleId;
+                    const acknowledgement = subcommand?.acknowledgement ?? command.acknowledgement;
+                    if (acknowledgement === "deferred-ephemeral") {
+                        await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+                    }
+                    if (await authorizeCommand(interaction, ownerModuleId, permissionId, subcommand?.rateLimit ?? command.rateLimit, services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
+                        false, subcommand?.authorization === "resource-scoped", owner?.moduleName)) {
                         const context = createCommandContext(interaction, services);
                         await execute(context);
                     }
@@ -187,10 +218,7 @@ export function installInteractions(client, modules, registration, logger, servi
     return registrationReady;
 }
 export function buildApplicationCommandDefinitions(modules, internalGuildId) {
-    const commands = uniqueMap(modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        contribution,
-    }))), ({ contribution }) => contribution.name, "command name");
+    const commands = collectCommandRegistrations(modules);
     const global = [...commands.values()]
         .filter(({ contribution }) => contribution.registration === "global")
         .map(toCommandDefinition);
@@ -201,11 +229,11 @@ export function buildApplicationCommandDefinitions(modules, internalGuildId) {
         throw new Error("DISCORD_INTERNAL_GUILD_ID is required when guild commands are loaded");
     return { global, guild };
 }
-export function resolveCommandExecutor(command, subcommandName) {
-    if (command.subcommands?.length) {
+export function resolveCommandExecutor(command, subcommandName, groupName = null) {
+    if (hasNestedCommands(command)) {
         if (!subcommandName)
             return undefined;
-        const subcommand = command.subcommands.find(({ name }) => name === subcommandName);
+        const subcommand = resolveCommandSubcommand(command, subcommandName, groupName);
         return subcommand ? (context) => subcommand.execute(context) : undefined;
     }
     return command.execute
@@ -214,11 +242,25 @@ export function resolveCommandExecutor(command, subcommandName) {
 }
 export function toCommandDefinition(registered) {
     const command = registered.contribution;
-    if (!!command.execute === !!command.subcommands?.length) {
-        throw new Error(`Command ${command.name} must define either execute or subcommands`);
+    const hasNested = Boolean(command.subcommands?.length || command.subcommandGroups?.length);
+    if (Number(command.execute !== undefined) + Number(hasNested) !== 1) {
+        throw new Error(`Command ${command.name} must define exactly one of execute, subcommands or subcommand groups`);
+    }
+    if (command.execute && !command.acknowledgement) {
+        throw new Error(`Command ${command.name} must declare acknowledgement`);
+    }
+    for (const subcommand of command.subcommands ?? []) {
+        if (!subcommand.acknowledgement && !command.acknowledgement)
+            throw new Error(`Command ${command.name}.${subcommand.name} must declare acknowledgement`);
+    }
+    for (const group of command.subcommandGroups ?? []) {
+        for (const subcommand of group.subcommands) {
+            if (!subcommand.acknowledgement && !command.acknowledgement)
+                throw new Error(`Command ${command.name}.${group.name}.${subcommand.name} must declare acknowledgement`);
+        }
     }
-    if (command.options?.length && command.subcommands?.length) {
-        throw new Error(`Command ${command.name} cannot define both direct options and subcommands`);
+    if (command.options?.length && hasNested) {
+        throw new Error(`Command ${command.name} cannot define both direct options and nested commands`);
     }
     const contextTypes = {
         guild: InteractionContextType.Guild,
@@ -248,8 +290,50 @@ export function toCommandDefinition(registered) {
             return subcommandBuilder;
         });
     }
+    for (const group of command.subcommandGroups ?? []) {
+        builder.addSubcommandGroup((groupBuilder) => {
+            groupBuilder.setName(group.name).setDescription(group.description);
+            for (const subcommand of group.subcommands) {
+                groupBuilder.addSubcommand((subcommandBuilder) => {
+                    subcommandBuilder
+                        .setName(subcommand.name)
+                        .setDescription(subcommand.description);
+                    for (const option of subcommand.options ?? []) {
+                        addCommandOption(subcommandBuilder, option);
+                    }
+                    return subcommandBuilder;
+                });
+            }
+            return groupBuilder;
+        });
+    }
     return builder.toJSON();
 }
+function hasNestedCommands(command) {
+    return Boolean(command?.subcommands?.length || command?.subcommandGroups?.length);
+}
+function resolveCommandSubcommand(command, subcommandName, groupName) {
+    if (!command || !subcommandName)
+        return undefined;
+    if (!groupName) {
+        return command.subcommands?.find(({ name }) => name === subcommandName);
+    }
+    return command.subcommandGroups
+        ?.find(({ name }) => name === groupName)
+        ?.subcommands.find(({ name }) => name === subcommandName);
+}
+function resolveCommandOwner(registered, subcommandName, groupName) {
+    if (!registered?.routeOwners || !subcommandName)
+        return undefined;
+    const path = groupName ? `${groupName}.${subcommandName}` : subcommandName;
+    return registered.routeOwners.get(path);
+}
+function commandChoices(command) {
+    return [
+        ...(command.subcommands ?? []).map(({ name }) => `\`/${command.name} ${name}\``),
+        ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.map(({ name }) => `\`/${command.name} ${group.name} ${name}\``)),
+    ];
+}
 function addCommandOption(builder, option) {
     if (option.type === "string") {
         if (option.autocomplete && option.choices?.length)
@@ -610,14 +694,20 @@ export async function addChannelMessageReaction(client, channelId, messageId, em
     const message = await channel.messages.fetch(messageId);
     await message.react(emojiIdentifier);
 }
-async function authorizeComponent(interaction, moduleId, services) {
+async function authorizeComponent(interaction, moduleId, services, requiredModuleName) {
+    if (!(await moduleIsGloballyAvailable(services, moduleId))) {
+        await replyEphemeralText(interaction, GLOBAL_MODULE_UNAVAILABLE_MESSAGE);
+        return false;
+    }
     if (!interaction.guildId)
         return true;
     const installations = services.get(HELYX_SERVICE_NAMES.installations);
     if (await installations.isModuleEnabled(interaction.guildId, moduleId)) {
         return true;
     }
-    await replyEphemeralText(interaction, "This module is disabled in this server. Ask a server administrator to enable it with `/helyx` or in the Helyx dashboard.");
+    await replyEphemeralText(interaction, requiredModuleName
+        ? `This command needs ${requiredModuleName}. Ask a server administrator to enable it in the Helyx dashboard.`
+        : "This module is disabled in this server. Ask a server administrator to enable it with `/helyx` or in the Helyx dashboard.");
     return false;
 }
 async function replyEphemeralText(interaction, content) {
@@ -627,11 +717,11 @@ async function replyEphemeralText(interaction, content) {
     }
     await interaction.reply({ content, flags: MessageFlags.Ephemeral });
 }
-export async function authorizeCommand(interaction, moduleId, commandId, rateLimit, services, selfAuthorizingGuildCommand, resourceScopedCommand = false) {
+export async function authorizeCommand(interaction, moduleId, commandId, rateLimit, services, selfAuthorizingGuildCommand, resourceScopedCommand = false, requiredModuleName) {
     if (!interaction.guildId)
         return true;
     if (!selfAuthorizingGuildCommand) {
-        if (!(await authorizeComponent(interaction, moduleId, services)))
+        if (!(await authorizeComponent(interaction, moduleId, services, requiredModuleName)))
             return false;
         if (!resourceScopedCommand) {
             const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
@@ -639,10 +729,7 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
             const actor = permissionActor(interaction);
             const guildAccess = await permissions.getGuildAccessPolicy?.(interaction.guildId);
             if (!canUseCommand(actor, policy, guildAccess)) {
-                await interaction.reply({
-                    content: "You do not have permission to use this command.",
-                    flags: MessageFlags.Ephemeral,
-                });
+                await replyEphemeralText(interaction, "You do not have permission to use this command.");
                 return false;
             }
         }
@@ -657,16 +744,15 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
             windowSeconds: rateLimit.windowSeconds,
         });
         if (!result.allowed) {
-            await interaction.reply({
-                content: `This command is temporarily rate limited. Try again <t:${Math.ceil(result.resetsAt.getTime() / 1_000)}:R>.`,
-                flags: MessageFlags.Ephemeral,
-            });
+            await replyEphemeralText(interaction, `This command is temporarily rate limited. Try again <t:${Math.ceil(result.resetsAt.getTime() / 1_000)}:R>.`);
             return false;
         }
     }
     return true;
 }
 async function authorizeAutocomplete(interaction, moduleId, commandId, services, selfAuthorizingGuildCommand, resourceScopedCommand) {
+    if (!(await moduleIsGloballyAvailable(services, moduleId)))
+        return false;
     if (!interaction.guildId || selfAuthorizingGuildCommand)
         return true;
     const installations = services.get(HELYX_SERVICE_NAMES.installations);
@@ -1023,6 +1109,7 @@ function interactionLogContext(interaction) {
         ...(interaction.isChatInputCommand()
             ? {
                 commandName: interaction.commandName,
+                subcommandGroupName: interaction.options.getSubcommandGroup(false) ?? undefined,
                 subcommandName: interaction.options.getSubcommand(false) ?? undefined,
             }
             : "customId" in interaction && typeof interaction.customId === "string"

package/dist/management-module.js

@@ -1,3 +1,4 @@
+import { isCustomerSelectableModule, } from "@helyx/module-manifest";
 import { defineModule, HELYX_SERVICE_NAMES, ModuleStateValidationError, } from "@helyx/sdk";
 const MODULE_SELECT_ID = "helyx.management.module";
 const SETTING_SELECT_ID = "helyx.management.setting";
@@ -24,7 +25,9 @@ const VIOLET = 0x7c3aed;
 const SUCCESS = 0x16a34a;
 const DANGER = 0xdc2626;
 export function createManagementModule(configurableModules, resources) {
-    const modules = [...configurableModules].sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
+    const modules = configurableModules
+        .filter((module) => isCustomerSelectableModule(module.manifest))
+        .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
     const byId = new Map(modules.map((module) => [module.manifest.id, module]));
     return defineModule({
         manifest: {
@@ -49,6 +52,7 @@ export function createManagementModule(configurableModules, resources) {
                 {
                     name: "helyx",
                     description: "Manage Helyx modules and settings",
+                    acknowledgement: "deferred-ephemeral",
                     registration: "global",
                     contexts: ["guild"],
                     integrationTypes: ["guild_install"],

package/dist/module-availability-control.d.ts

@@ -0,0 +1,24 @@
+import { type ModuleAvailabilityService, type ModuleAvailabilityState, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+export interface AvailabilityModuleDefinition {
+    id: string;
+    name: string;
+    version: string;
+    releaseStatus: "planned" | "testing" | "beta" | "live";
+}
+export interface AvailabilityModuleCatalogue {
+    catalogueDigest: string;
+    modules: AvailabilityModuleDefinition[];
+}
+export declare function availabilityCatalogueDefinitions(modules: readonly ModuleDefinition[]): AvailabilityModuleDefinition[];
+export declare function availabilityCatalogueSnapshot(definitions: readonly AvailabilityModuleDefinition[]): AvailabilityModuleCatalogue;
+export declare function availabilityCatalogue(definitions: readonly AvailabilityModuleDefinition[]): Promise<AvailabilityModuleCatalogue>;
+export declare function moduleAvailabilityService(services: ServiceAccess): ModuleAvailabilityService | undefined;
+export declare function moduleAvailabilityStates(services: ServiceAccess, moduleIds: readonly string[]): Promise<ModuleAvailabilityState[]>;
+export declare function dashboardModuleStatus(globallyDisabled: ReadonlySet<string>, moduleId: string, installation: {
+    enabled: boolean;
+} | undefined): "enabled" | "disabled" | "unavailable";
+export declare function disabledModuleSummary(states: readonly ModuleAvailabilityState[]): {
+    ids: string[];
+    set: ReadonlySet<string>;
+};
+//# sourceMappingURL=module-availability-control.d.ts.map

package/dist/module-availability-control.js

@@ -0,0 +1,61 @@
+import { isCustomerSelectableModule } from "@helyx/module-manifest";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createHash } from "node:crypto";
+export function availabilityCatalogueDefinitions(modules) {
+    return modules
+        .filter((module) => isCustomerSelectableModule(module.manifest))
+        .map(({ manifest }) => ({
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        releaseStatus: manifest.releaseStatus,
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name, "en-GB"));
+}
+export function availabilityCatalogueSnapshot(definitions) {
+    const modules = definitions.map((module) => ({ ...module }));
+    return {
+        catalogueDigest: createHash("sha256")
+            .update(JSON.stringify(modules))
+            .digest("hex"),
+        modules,
+    };
+}
+export function availabilityCatalogue(definitions) {
+    return Promise.resolve(availabilityCatalogueSnapshot(definitions));
+}
+export function moduleAvailabilityService(services) {
+    if (!services.has(HELYX_SERVICE_NAMES.moduleAvailability))
+        return undefined;
+    const service = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
+    return typeof service?.get === "function" &&
+        typeof service.isAvailable === "function"
+        ? service
+        : undefined;
+}
+export function moduleAvailabilityStates(services, moduleIds) {
+    const availability = moduleAvailabilityService(services);
+    return Promise.all(moduleIds.map((moduleId) => availability
+        ? availability.get(moduleId)
+        : Promise.resolve({
+            moduleId,
+            globallyDisabled: false,
+            revision: 0n,
+            generation: 0n,
+            updatedAt: null,
+        })));
+}
+export function dashboardModuleStatus(globallyDisabled, moduleId, installation) {
+    if (globallyDisabled.has(moduleId))
+        return "unavailable";
+    if (!installation)
+        return "unavailable";
+    return installation.enabled ? "enabled" : "disabled";
+}
+export function disabledModuleSummary(states) {
+    const ids = states
+        .filter(({ globallyDisabled }) => globallyDisabled)
+        .map(({ moduleId }) => moduleId);
+    return { ids, set: new Set(ids) };
+}
+//# sourceMappingURL=module-availability-control.js.map

package/dist/modules.js

@@ -1,4 +1,5 @@
 import { orderModuleManifests, parseModuleManifest, } from "@helyx/module-manifest";
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID } from "@helyx/sdk";
 import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -102,6 +103,28 @@ export function validateContributionParity(definition) {
         throw new Error("Module requests an unsupported or duplicate Discord capability");
     }
     const executableCommands = (definition.interactions?.commands ?? []).map(({ name }) => name);
+    const nexusCommandPaths = new Set();
+    for (const command of definition.nexusCommands ?? []) {
+        const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === command.path);
+        if (!spec || spec.ownerModuleId !== definition.manifest.id) {
+            throw new Error(`Module ${definition.manifest.id} cannot contribute Nexus command ${command.path}`);
+        }
+        if (nexusCommandPaths.has(command.path)) {
+            throw new Error(`Duplicate Nexus command path for ${definition.manifest.id}: ${command.path}`);
+        }
+        nexusCommandPaths.add(command.path);
+    }
+    if (definition.manifest.id !== NEXUS_ROOT_MODULE_ID) {
+        executableCommands.push(...[...nexusCommandPaths].map((path) => `nexus.${path}`));
+        if (nexusCommandPaths.size > 0 &&
+            !definition.manifest.dependencies.some(({ id }) => id === NEXUS_ROOT_MODULE_ID)) {
+            throw new Error(`Module ${definition.manifest.id} contributes Nexus commands without depending on Nexus Core`);
+        }
+    }
+    if (definition.manifest.id !== NEXUS_ROOT_MODULE_ID &&
+        definition.interactions?.commands?.some(({ name }) => name === "nexus")) {
+        throw new Error("Nexus Core must be the sole owner of /nexus");
+    }
     const executableEvents = [
         ...(definition.events?.privilegedMessageCreate ?? []),
         ...(definition.events?.guildMessageCreate ?? []),
@@ -135,7 +158,7 @@ export function validateContributionParity(definition) {
 function validatePrivacyParity(definition) {
     if (definition.manifest.manifestVersion === "0.1") {
         if (definition.privacy !== undefined) {
-            throw new Error("Module executable privacy provider requires manifest version 0.2");
+            throw new Error("Module executable privacy provider requires manifest version 0.2 or later");
         }
         return;
     }

package/dist/nexus-commands.d.ts

@@ -0,0 +1,13 @@
+import { type CommandContribution, type ModuleDefinition } from "@helyx/sdk";
+export interface CommandRouteOwner {
+    moduleId: string;
+    moduleName: string;
+}
+export interface RegisteredCommand {
+    moduleId: string;
+    moduleName: string;
+    contribution: CommandContribution;
+    routeOwners?: ReadonlyMap<string, CommandRouteOwner>;
+}
+export declare function collectCommandRegistrations(modules: readonly ModuleDefinition[]): Map<string, RegisteredCommand>;
+//# sourceMappingURL=nexus-commands.d.ts.map

package/dist/nexus-commands.js

@@ -0,0 +1,100 @@
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID, } from "@helyx/sdk";
+export function collectCommandRegistrations(modules) {
+    const registrations = modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        moduleName: module.manifest.name,
+        contribution,
+    })));
+    const nexusContributions = modules.flatMap((module) => (module.nexusCommands ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        moduleName: module.manifest.name,
+        contribution,
+    })));
+    if (nexusContributions.length > 0) {
+        const roots = registrations.filter(({ contribution }) => contribution.name === "nexus");
+        if (roots.length !== 1 || roots[0].moduleId !== NEXUS_ROOT_MODULE_ID) {
+            throw new Error("Nexus Core must be the sole owner of /nexus");
+        }
+        const root = roots[0];
+        if (root.contribution.execute ||
+            root.contribution.options?.length ||
+            root.contribution.subcommands?.length ||
+            root.contribution.subcommandGroups?.length) {
+            throw new Error("Nexus Core /nexus must be composed from Nexus commands");
+        }
+        const composed = composeNexusCommand(root, nexusContributions);
+        registrations.splice(registrations.indexOf(root), 1, composed);
+    }
+    return uniqueRegistrations(registrations);
+}
+function composeNexusCommand(root, contributions) {
+    const byPath = new Map(contributions.map((item) => {
+        const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === item.contribution.path);
+        if (!spec || spec.ownerModuleId !== item.moduleId) {
+            throw new Error(`Module ${item.moduleId} cannot contribute Nexus command ${item.contribution.path}`);
+        }
+        return [item.contribution.path, item];
+    }));
+    if (byPath.size !== contributions.length) {
+        throw new Error("Duplicate Nexus command path");
+    }
+    const subcommands = [];
+    const groups = new Map();
+    const routeOwners = new Map();
+    for (const spec of NEXUS_COMMAND_SPECS) {
+        const item = byPath.get(spec.path);
+        if (!item)
+            continue;
+        routeOwners.set(spec.path, {
+            moduleId: item.moduleId,
+            moduleName: item.moduleName,
+        });
+        const [first, second] = spec.path.split(".");
+        const command = toSubcommand(item.contribution, second ?? first);
+        if (!second) {
+            subcommands.push(command);
+            continue;
+        }
+        const current = groups.get(first);
+        const group = current ?? {
+            name: first,
+            description: "groupDescription" in spec
+                ? spec.groupDescription
+                : `Manage Nexus ${first}`,
+            subcommands: [],
+        };
+        groups.set(first, {
+            ...group,
+            subcommands: [...group.subcommands, command],
+        });
+    }
+    return {
+        ...root,
+        contribution: {
+            ...root.contribution,
+            subcommands,
+            subcommandGroups: [...groups.values()],
+        },
+        routeOwners,
+    };
+}
+function toSubcommand(contribution, name) {
+    const subcommand = {
+        ...contribution,
+        name,
+        permissionId: `nexus.${contribution.path}`,
+    };
+    delete subcommand.path;
+    return subcommand;
+}
+function uniqueRegistrations(items) {
+    const result = new Map();
+    for (const item of items) {
+        const key = item.contribution.name;
+        if (result.has(key))
+            throw new Error(`Duplicate command name: ${key}`);
+        result.set(key, item);
+    }
+    return result;
+}
+//# sourceMappingURL=nexus-commands.js.map

package/dist/oauth-module.js

@@ -43,6 +43,7 @@ export function createOAuthModule() {
                         {
                             name: "revoke",
                             description: "Revoke a service and delete the OAuth details Helyx stores for you.",
+                            acknowledgement: "immediate-modal",
                             rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
                             execute: async (context) => {
                                 const oauth = context.services.get(HELYX_SERVICE_NAMES.oauth);