@helyx/bot 0.4.37 → 0.4.39

package/dist/shard-contracts.d.ts

@@ -208,6 +208,14 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
     guildId: z.ZodString;
     moduleId: z.ZodString;
     enabled: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    actorUserId: z.ZodString;
+    correlationId: z.ZodString;
+    kind: z.ZodLiteral<"guild.commands.first-time-setup">;
+    guildId: z.ZodString;
+    moduleIds: z.ZodArray<z.ZodString>;
+    expectedRevision: z.ZodString;
+    idempotencyKey: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     actorUserId: z.ZodString;
     correlationId: z.ZodString;
@@ -561,6 +569,14 @@ export declare const shardControlRequestSchema: z.ZodObject<{
         guildId: z.ZodString;
         moduleId: z.ZodString;
         enabled: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.commands.first-time-setup">;
+        guildId: z.ZodString;
+        moduleIds: z.ZodArray<z.ZodString>;
+        expectedRevision: z.ZodString;
+        idempotencyKey: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;
         correlationId: z.ZodString;
@@ -1419,6 +1435,14 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         guildId: z.ZodString;
         moduleId: z.ZodString;
         enabled: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.commands.first-time-setup">;
+        guildId: z.ZodString;
+        moduleIds: z.ZodArray<z.ZodString>;
+        expectedRevision: z.ZodString;
+        idempotencyKey: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;
         correlationId: z.ZodString;

package/dist/shard-contracts.js

@@ -280,6 +280,16 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         ...mutationContext.shape,
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal("guild.commands.first-time-setup"),
+        guildId: snowflake,
+        moduleIds: z.array(moduleId).min(1).max(100),
+        expectedRevision: z.string().regex(/^\d+$/u),
+        idempotencyKey: z.string().min(1).max(160),
+        ...mutationContext.shape,
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("guild.module.configuration.update"),
@@ -992,6 +1002,16 @@ export async function executeShardControlOperation(handler, operation) {
                 correlationId: operation.correlationId,
             });
         }
+        case "guild.commands.first-time-setup": {
+            return handler.completeFirstTimeCommandSetup({
+                guildId: operation.guildId,
+                moduleIds: operation.moduleIds,
+                expectedRevision: BigInt(operation.expectedRevision),
+                idempotencyKey: operation.idempotencyKey,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            });
+        }
         case "guild.module.configuration.update": {
             return handler.updateConfiguration({
                 guildId: operation.guildId,

package/dist/shard-router.d.ts

@@ -26,6 +26,7 @@ export declare class ShardControlRouter implements BotControlHandler {
     canAccessManagedResource(input: Parameters<BotControlHandler["canAccessManagedResource"]>[0]): ReturnType<BotControlHandler["canAccessManagedResource"]>;
     listGuildPresence(input: Parameters<BotControlHandler["listGuildPresence"]>[0]): ReturnType<BotControlHandler["listGuildPresence"]>;
     setModuleStatus(input: Parameters<BotControlHandler["setModuleStatus"]>[0]): ReturnType<BotControlHandler["setModuleStatus"]>;
+    completeFirstTimeCommandSetup(input: Parameters<BotControlHandler["completeFirstTimeCommandSetup"]>[0]): ReturnType<BotControlHandler["completeFirstTimeCommandSetup"]>;
     updateConfiguration(input: Parameters<BotControlHandler["updateConfiguration"]>[0]): ReturnType<BotControlHandler["updateConfiguration"]>;
     updatePermissions(input: Parameters<BotControlHandler["updatePermissions"]>[0]): ReturnType<BotControlHandler["updatePermissions"]>;
     updateLoggingPolicy(input: Parameters<BotControlHandler["updateLoggingPolicy"]>[0]): ReturnType<BotControlHandler["updateLoggingPolicy"]>;

package/dist/shard-router.js

@@ -84,6 +84,13 @@ export class ShardControlRouter {
     setModuleStatus(input) {
         return this.#route({ kind: "guild.module.status.set", ...input });
     }
+    completeFirstTimeCommandSetup(input) {
+        return this.#route({
+            kind: "guild.commands.first-time-setup",
+            ...input,
+            expectedRevision: input.expectedRevision.toString(),
+        });
+    }
     updateConfiguration(input) {
         return this.#route(shardControlOperationSchema.parse({
             kind: "guild.module.configuration.update",

package/dist/shard-supervisor.d.ts

@@ -1,6 +1,7 @@
 import type { BotEnvironment } from "@helyx/config";
 import { type DatabasePool } from "@helyx/database";
 import type { ModuleDefinition, NumericWriteBehindCommittedBatch, ScheduledTaskExecutionResult } from "@helyx/sdk";
+import { buildApplicationCommandDefinitions } from "./interactions.js";
 import { type ShardCloudRequest, type ShardIdentity, type ShardProcessHealth } from "./shard-contracts.js";
 import { type ShardCoordinator, type ShardGenerationDescriptor, type ShardLeaderLease, type ShardLease } from "./shard-coordinator.js";
 import type { BotHandle } from "./index.js";
@@ -18,7 +19,7 @@ export declare function deferScheduledRoutingFailures(route: () => Promise<Sched
 export declare function startShardSupervisor(environment: BotEnvironment, processEnvironment: NodeJS.ProcessEnv, workerEntry: string): Promise<BotHandle>;
 export declare function splitNumericCommittedBatch(batch: NumericWriteBehindCommittedBatch, index: number): NumericWriteBehindCommittedBatch;
 export declare function buildShardWorkerEnvironment(source: NodeJS.ProcessEnv, identity: ShardIdentity, restartCount: number): NodeJS.ProcessEnv;
-export declare function shardRuntimeCompositionHash(modules: readonly ModuleDefinition[], internalGuildId?: string): string;
+export declare function shardRuntimeCompositionHash(modules: readonly ModuleDefinition[], internalGuildId?: string, globalCommandMode?: Parameters<typeof buildApplicationCommandDefinitions>[2]): string;
 export declare function boundedRespawnDelay(attempt: number): number;
 export interface SteadyStateOwnershipRenewal {
     generationRenewed: boolean;

package/dist/shard-supervisor.js

@@ -1,5 +1,5 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
@@ -23,11 +23,18 @@ import { createDeveloperOperationsModule } from "./developer-operations-module.j
 import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
+import { createPrivacyModule } from "./privacy-module.js";
+import { discordRestOptions } from "./discord-rest.js";
 import { availabilityCatalogue, availabilityCatalogueDefinitions, } from "./module-availability-control.js";
 import { createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
 import { numericWriteBehindRegistrations } from "./numeric-write-behind.js";
+import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { executeRedisNumericOperation, RedisNumericWriteBehindService, } from "./numeric-write-behind-redis.js";
 import { encodeNumericIpcValue } from "./numeric-write-behind-proxy.js";
+import { GuildCommandWorker } from "./guild-command-worker.js";
+import { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
+import { GuildCommandReadService } from "./guild-command-read-service.js";
+import { scheduleGuildCommandRelease } from "./guild-command-release.js";
 const LEASE_RENEW_INTERVAL_MS = 10_000;
 const STARTUP_LEASE_RENEW_INTERVAL_MS = 5_000;
 const LEASE_VALIDATION_TIMEOUT_MS = 1_000;
@@ -137,7 +144,10 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let privacyService;
     let manager;
     let scheduledTasks;
+    let guildCommandWorker;
+    let guildCommandReleasePromise;
     let scheduledModules = [];
+    let commandModules = [];
     let workersRoutable = false;
     let promoteToLeader = () => Promise.resolve(false);
     try {
@@ -171,7 +181,10 @@ export async function startShardSupervisor(environment, processEnvironment, work
             coreVersion: botVersion(),
             logger,
         });
-        const commandClient = new Client({ intents: [] });
+        const commandClient = new Client({
+            intents: [],
+            rest: discordRestOptions,
+        });
         const unavailableResources = {
             listGuildPresence: (guildIds) => Promise.resolve(guildIds.map((guildId) => ({
                 guildId,
@@ -197,6 +210,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             })
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
+        const privacyModule = createPrivacyModule();
         const oauthModule = environment.HELYX_OAUTH_ENABLED
             ? createOAuthModule()
             : undefined;
@@ -204,6 +218,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             managementModule,
             permissionsModule,
             supportModule,
+            privacyModule,
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
@@ -224,11 +239,13 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     managementModule,
                     permissionsModule,
                     supportModule,
+                    privacyModule,
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
                 modules: featureModules.map(({ manifest }) => manifest),
                 processLabel: "shard supervisor registration",
+                triviaData: new PostgresTriviaDataProvider(database),
                 health: {
                     getHealth: async () => boundedOperationalHealth(await buildHealth()),
                 },
@@ -238,6 +255,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             ...publicModules,
             ...(operationsModule ? [operationsModule] : []),
         ];
+        commandModules = modules;
         const availabilityModules = availabilityCatalogueDefinitions(modules);
         const availabilityService = {
             listAvailabilityModules: () => availabilityCatalogue(availabilityModules),
@@ -289,7 +307,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             environment: environment.NODE_ENV,
             generation,
             shardCount,
-            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID),
+            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID, environment.HELYX_GLOBAL_COMMAND_MODE),
         };
         deploymentOrder = await nextShardDeploymentOrder(database);
         if (environment.HELYX_SHARD_SCOPE === "coordinated") {
@@ -402,6 +420,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 secret: environment.HELYX_BOT_CONTROL_SECRET,
                 logger: { level: environment.LOG_LEVEL },
                 shardHealth: buildHealth,
+                guildCommands: new GuildCommandReadService(database, environment.DISCORD_CLIENT_ID, () => guildCommandWorker?.getHealth(), environment.DISCORD_TOKEN, environment.HELYX_GUILD_COMMAND_WRITES_ENABLED, environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS, environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all", commandModules),
             });
             await controlServer.listen({
                 host: "::",
@@ -1087,16 +1106,62 @@ export async function startShardSupervisor(environment, processEnvironment, work
             startScheduledTasks();
     }
     function startScheduledTasks() {
-        if (scheduledTasks || !leaderLease || !workersRoutable)
+        if (!leaderLease || !workersRoutable)
             return;
-        scheduledTasks = createScheduledTaskRunner({
-            database,
-            modules: scheduledModules,
-            route: routeScheduledTask,
-            logger,
-            workerId: `shard-leader:${leaderLease.generation}:${String(leaderLease.fencingToken)}`,
-        });
-        scheduledTasks.start();
+        if (!scheduledTasks) {
+            scheduledTasks = createScheduledTaskRunner({
+                database,
+                modules: scheduledModules,
+                route: routeScheduledTask,
+                logger,
+                workerId: `shard-leader:${leaderLease.generation}:${String(leaderLease.fencingToken)}`,
+            });
+            scheduledTasks.start();
+        }
+        if (!guildCommandWorker) {
+            guildCommandWorker = new GuildCommandWorker({
+                database,
+                modules: commandModules,
+                logger,
+                workerId: `shard-leader-command:${leaderLease.generation}:${String(leaderLease.fencingToken)}`,
+                fencingToken: BigInt(leaderLease.fencingToken),
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                ...(environment.HELYX_GUILD_COMMAND_WRITES_ENABLED
+                    ? {
+                        discord: new GuildCommandDiscordClient({
+                            applicationId: environment.DISCORD_CLIENT_ID,
+                            token: environment.DISCORD_TOKEN,
+                            writeGuildIds: environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS,
+                            writeAllGuilds: environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all",
+                        }),
+                    }
+                    : {}),
+            });
+            guildCommandWorker.start();
+        }
+        if (environment.HELYX_GUILD_COMMAND_WRITES_ENABLED &&
+            environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all" &&
+            !guildCommandReleasePromise) {
+            const releasePromise = scheduleGuildCommandRelease({
+                database,
+                applicationId: environment.DISCORD_CLIENT_ID,
+                releaseId: environment.HELYX_GUILD_COMMAND_RELEASE_ID,
+            })
+                .then((release) => {
+                logger.info({ event: "guild_commands.release_scheduled", ...release }, "Guild command release rollout prepared");
+            })
+                .catch((error) => {
+                if (guildCommandReleasePromise === releasePromise)
+                    guildCommandReleasePromise = undefined;
+                logger.error({
+                    event: "guild_commands.release_schedule_failed",
+                    error: safeError(error),
+                }, "Guild command release rollout could not be prepared");
+            });
+            guildCommandReleasePromise = releasePromise;
+        }
     }
     async function routeScheduledTask(task, signal) {
         if (!task.guildId)
@@ -1296,6 +1361,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
         workersRoutable = false;
         await scheduledTasks?.stop().catch(() => undefined);
         scheduledTasks = undefined;
+        await guildCommandWorker?.stop().catch(() => undefined);
+        guildCommandWorker = undefined;
         for (const [requestId, pending] of pendingScheduled) {
             clearTimeout(pending.timer);
             pending.resolve(unavailableScheduled(requestId, "supervisor_stopping"));
@@ -1366,9 +1433,11 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
         applicationId: environment.DISCORD_CLIENT_ID,
         token: environment.DISCORD_TOKEN,
         modules,
+        globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
         ...(environment.DISCORD_INTERNAL_GUILD_ID
             ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
             : {}),
+        synchroniseInternalGuild: !environment.HELYX_GUILD_COMMAND_WRITES_ENABLED,
         state: new RuntimeCommandHashStore(repository),
     });
     await setRuntimeState(repository, `shards:${environment.HELYX_SHARD_GENERATION ?? "local"}:startup`, {
@@ -1514,8 +1583,8 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         HELYX_SHARD_RESTART_COUNT: String(restartCount),
     };
 }
-export function shardRuntimeCompositionHash(modules, internalGuildId) {
-    const commands = buildApplicationCommandDefinitions(modules, internalGuildId);
+export function shardRuntimeCompositionHash(modules, internalGuildId, globalCommandMode = "legacy") {
+    const commands = buildApplicationCommandDefinitions(modules, internalGuildId, globalCommandMode);
     return createHash("sha256")
         .update(JSON.stringify({
         botVersion: botVersion(),
@@ -1581,17 +1650,26 @@ function failedCloud(requestId, message) {
 }
 async function cleanupExpiredCoreRecords(database, logger) {
     try {
-        const [sessions, rateLimits, verificationAudit] = await Promise.all([
+        const [sessions, rateLimits, verificationAudit, commandRecords] = await Promise.all([
             new InteractionSessionRepository(database).deleteExpired(),
             new RateLimitRepository(database).deleteExpired(),
             new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
+            new GuildCommandRepository(database).deleteExpired(12),
         ]);
-        if (sessions > 0 || rateLimits > 0 || verificationAudit > 0)
+        const commandRecordCount = commandRecords.history +
+            commandRecords.idempotencyKeys +
+            commandRecords.creationLedger +
+            commandRecords.requests;
+        if (sessions > 0 ||
+            rateLimits > 0 ||
+            verificationAudit > 0 ||
+            commandRecordCount > 0)
             logger.info({
                 event: "database.retention_cleaned",
                 interactionSessions: sessions,
                 rateLimitWindows: rateLimits,
                 verificationAuditEvents: verificationAudit,
+                commandRecords: commandRecordCount,
             }, "Expired core records removed");
     }
     catch (error) {

package/dist/shard-worker.d.ts

@@ -40,6 +40,10 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_VERIFICATION_SIGNING_PUBLIC_KEYS: Record<string, string>;
     HELYX_BOT_CONTROL_PORT: number;
     HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS: number;
+    HELYX_GUILD_COMMAND_WRITES_ENABLED: boolean;
+    HELYX_GUILD_COMMAND_WRITE_SCOPE: "allowlist" | "all";
+    HELYX_GLOBAL_COMMAND_MODE: "legacy" | "platform-only";
+    HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: string[];
     HELYX_PRIVACY_ENABLED: boolean;
     HELYX_MESSAGE_CONTENT_ENABLED: boolean;
     HELYX_GUILD_MEMBERS_ENABLED: boolean;
@@ -64,6 +68,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_VERIFICATION_INSTALLATION_ID?: string | undefined;
     HELYX_VERIFICATION_URL?: string | undefined;
     HELYX_VERIFICATION_INTERNAL_SECRET?: string | undefined;
+    HELYX_GUILD_COMMAND_RELEASE_ID?: string | undefined;
     HELYX_PRIVACY_EXECUTOR_DATABASE_URL?: string | undefined;
     HELYX_PRIVACY_EXECUTOR_DATABASE_SSL?: "disable" | "require" | "verify-full" | undefined;
     HELYX_OAUTH_INTERNAL_SECRET?: string | undefined;

package/dist/shard-worker.js

@@ -22,15 +22,18 @@ import { WorkerCloudConnectorProxy } from "./shard-cloud-proxy.js";
 import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
 import { DiscordGuildHealthInspection } from "./discord-guild-health.js";
 import { CoreResourceAuthorizationService } from "./resource-authorization.js";
+import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
 import { assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, guildIdToShardId, SHARD_LEASE_HEARTBEAT_TIMEOUT_MS, shardIdentitySchema, supervisorMessageSchema, } from "./shard-contracts.js";
 import { gatewayIntentsForModules, readBotVersion, } from "./index.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
+import { createPrivacyModule } from "./privacy-module.js";
 import { HttpOAuthService } from "./oauth-service.js";
 import { createLocalScheduledTaskRoute, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
 import { WorkerNumericWriteBehindProxy } from "./numeric-write-behind-proxy.js";
+import { discordRestOptions } from "./discord-rest.js";
 const HEALTH_INTERVAL_MS = 5_000;
 export const WORKER_ORPHAN_TERMINATION_BOUND_MS = SHARD_LEASE_HEARTBEAT_TIMEOUT_MS + 5_000;
 export function createLeaseHeartbeatWatchdog(onExpired, timeoutMs = SHARD_LEASE_HEARTBEAT_TIMEOUT_MS) {
@@ -114,6 +117,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const featureModules = modulePackages.map(({ definition }) => definition);
         client = new Client({
+            rest: discordRestOptions,
             intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED, environment.HELYX_GUILD_MEMBERS_ENABLED),
             partials: [Partials.Message, Partials.Channel, Partials.Reaction],
             allowedMentions: { parse: [] },
@@ -133,6 +137,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             })
             : undefined;
         const supportModule = createSupportModule(cloudProxy);
+        const privacyModule = createPrivacyModule();
         const oauthModule = environment.HELYX_OAUTH_ENABLED
             ? createOAuthModule()
             : undefined;
@@ -140,6 +145,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             managementModule,
             permissionsModule,
             supportModule,
+            privacyModule,
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
@@ -159,11 +165,13 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     managementModule,
                     permissionsModule,
                     supportModule,
+                    privacyModule,
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
                 modules: featureModules.map(({ manifest }) => manifest),
                 processLabel: `shard worker ${identity.shardId}`,
+                triviaData: new PostgresTriviaDataProvider(database),
                 health: shardHealthProvider,
             })
             : undefined;
@@ -231,7 +239,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             shardId: identity.shardId,
             fencingToken: BigInt(identity.fencingToken),
         };
-        const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount, environment.DISCORD_CLIENT_ID);
         guildTracking = prepareGuilds;
         const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
             ...(environment.DISCORD_INTERNAL_GUILD_ID

package/dist/shared-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=shared-commands.d.ts.map

package/dist/shared-commands.js

@@ -0,0 +1,163 @@
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID, SHARED_COMMAND_FAMILY_SPECS, } from "@helyx/sdk";
+const nexusFamilySpec = {
+    name: "nexus",
+    description: "View and manage Nexus",
+    registrationPolicy: "enabled-guild",
+    contexts: ["guild"],
+    integrationTypes: ["guild_install"],
+    paths: NEXUS_COMMAND_SPECS,
+};
+const familySpecs = [
+    ...SHARED_COMMAND_FAMILY_SPECS,
+    nexusFamilySpec,
+];
+export function collectCommandRegistrations(modules) {
+    const registrations = modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        moduleName: module.manifest.name,
+        contribution,
+    })));
+    const familyContributions = modules.flatMap((module) => [
+        ...(module.sharedCommands ?? []).map((contribution) => ({
+            moduleId: module.manifest.id,
+            moduleName: module.manifest.name,
+            contribution,
+        })),
+        ...(module.nexusCommands ?? []).map((contribution) => ({
+            moduleId: module.manifest.id,
+            moduleName: module.manifest.name,
+            contribution: fromNexusContribution(contribution),
+        })),
+    ]);
+    for (const family of familySpecs) {
+        const contributions = familyContributions.filter(({ contribution }) => contribution.family === family.name);
+        if (contributions.length === 0)
+            continue;
+        const roots = registrations.filter(({ contribution }) => contribution.name === family.name);
+        if (roots.length > 1)
+            throw new Error(`Shared command /${family.name} has multiple root owners`);
+        const explicitRoot = roots[0];
+        if (explicitRoot) {
+            validateExplicitRoot(family, explicitRoot);
+            registrations.splice(registrations.indexOf(explicitRoot), 1);
+        }
+        registrations.push(composeSharedCommand(family, explicitRoot ?? syntheticRoot(family, contributions), contributions));
+    }
+    const unknownFamily = familyContributions.find(({ contribution }) => !familySpecs.some(({ name }) => name === contribution.family));
+    if (unknownFamily)
+        throw new Error(`Unknown shared command family: ${unknownFamily.contribution.family}`);
+    return uniqueRegistrations(registrations);
+}
+function syntheticRoot(family, contributions) {
+    const owner = contributions[0];
+    return {
+        moduleId: owner.moduleId,
+        moduleName: owner.moduleName,
+        contribution: {
+            name: family.name,
+            description: family.description,
+            registrationPolicy: family.registrationPolicy,
+            contexts: family.contexts,
+            integrationTypes: family.integrationTypes,
+            subcommands: [],
+        },
+    };
+}
+function validateExplicitRoot(family, root) {
+    if (family.name !== "nexus" || root.moduleId !== NEXUS_ROOT_MODULE_ID)
+        throw new Error(`Shared command /${family.name} must use its composed root`);
+    if (root.contribution.execute ||
+        root.contribution.options?.length ||
+        root.contribution.subcommands?.length ||
+        root.contribution.subcommandGroups?.length) {
+        throw new Error(`Shared command /${family.name} root must be empty`);
+    }
+}
+function composeSharedCommand(family, root, contributions) {
+    const byPath = new Map();
+    for (const item of contributions) {
+        const path = family.paths.find(({ path: candidate }) => candidate === item.contribution.path);
+        if (!path || path.ownerModuleId !== item.moduleId) {
+            throw new Error(`Module ${item.moduleId} cannot contribute ${family.name} command ${item.contribution.path}`);
+        }
+        if (byPath.has(item.contribution.path))
+            throw new Error(`Duplicate shared command path: ${family.name}.${item.contribution.path}`);
+        byPath.set(item.contribution.path, item);
+    }
+    const subcommands = [];
+    const groups = new Map();
+    const routeOwners = new Map();
+    const contexts = new Set(family.contexts);
+    for (const pathSpec of family.paths) {
+        const item = byPath.get(pathSpec.path);
+        if (!item)
+            continue;
+        for (const context of item.contribution.contexts ?? [])
+            contexts.add(context);
+        routeOwners.set(pathSpec.path, {
+            moduleId: item.moduleId,
+            moduleName: item.moduleName,
+        });
+        const [first, second, ...rest] = pathSpec.path.split(".");
+        if (rest.length > 0)
+            throw new Error(`Shared command path is deeper than one group: ${family.name}.${pathSpec.path}`);
+        const command = toSubcommand(item.contribution, second ?? first, `${family.name}.${pathSpec.path}`);
+        if (!second) {
+            subcommands.push(command);
+            continue;
+        }
+        const current = groups.get(first);
+        const group = current ?? {
+            name: first,
+            description: pathSpec.groupDescription ?? `Manage ${family.name} ${first}`,
+            subcommands: [],
+        };
+        if (current &&
+            pathSpec.groupDescription &&
+            current.description !== pathSpec.groupDescription)
+            throw new Error(`Shared command group description mismatch: ${family.name}.${first}`);
+        groups.set(first, {
+            ...group,
+            subcommands: [...group.subcommands, command],
+        });
+    }
+    return {
+        ...root,
+        contribution: {
+            ...root.contribution,
+            contexts: [...contexts],
+            subcommands,
+            subcommandGroups: [...groups.values()],
+        },
+        routeOwners,
+    };
+}
+function toSubcommand(contribution, name, defaultPermissionId) {
+    const subcommand = {
+        ...contribution,
+        name,
+        permissionId: contribution.permissionId ?? defaultPermissionId,
+    };
+    delete subcommand.family;
+    delete subcommand.path;
+    delete subcommand.contexts;
+    return subcommand;
+}
+function fromNexusContribution(contribution) {
+    return {
+        ...contribution,
+        family: "nexus",
+        permissionId: `nexus.${contribution.path}`,
+    };
+}
+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=shared-commands.js.map