@helyx/bot 0.4.37 → 0.4.39

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.4.39
+
+### Patch Changes
+
+- 38c70f7: Ship maintained public documentation with the bot package and point newly generated self-host projects to its version-matched offline copy.
+
+## 0.4.38
+
+### Patch Changes
+
+- Add per-server command registration, shared command families, command-management controls, and the supporting configuration and persistence contracts.
+- Add `/dev trivia-data` so approved developers can inspect distinct Trivia question totals and category difficulty counts from the active database.
+- Make the per-server command worker the sole writer for managed guild command collections so startup cannot replace enabled module commands with the internal `/dev` command.
+- Add idempotent, staggered production command rollouts and authoritative first-time command previews from the live command projector.
+- Report exact command roots changed by successful Discord reconciliations.
+- Make static public platform commands respond without database authorization, avoid redundant platform availability reads, and run required customer command authorization reads concurrently.
+- Warm each shard's Discord REST connection during startup and fast-path public commands so the first modal response does not expire while opening a cold HTTPS connection.
+- Compose the Batch 1 Achievements, Feedback, and Suggestions routes under shared enabled-server roots, while retaining the complete Polls and FAQ command surfaces.
+- Report whether a failed module log delivery is retryable so modules do not queue work for intentionally disabled events.
+
 ## 0.4.37
 
 ### Patch Changes

package/README.md

@@ -2,15 +2,35 @@
 
 The Helyx Discord runtime validates its environment, verifies and migrates PostgreSQL, validates explicitly configured module packages, applies their migrations, composes platform services, synchronises guild installations and commands, logs in with the non-privileged Guilds intent, and shuts down Discord, modules, and PostgreSQL safely.
 
-Each command declares `registration: "global"` for every installed Discord server or `registration: "guild"` for the internal server. Set `DISCORD_INTERNAL_GUILD_ID` whenever a loaded module contains guild-only commands. Global and guild commands are synchronized independently.
+Version-matched public guides, operator runbooks, environment reference
+material, and module-authoring instructions ship at `documentation/README.md`
+inside this npm package. Repository-only `docs/` and `docs-old/` content is not
+published.
+
+Command contributions use an explicit registration policy: platform commands
+remain global, migrated customer commands are projected into enabled guilds,
+deployment commands stay with their deployment, and internal commands are
+limited to `DISCORD_INTERNAL_GUILD_ID`. Global and guild commands are
+synchronized independently.
 
 Registration uses Discord's bulk-overwrite operation, so both scopes are synchronized to exactly the commands supplied by the active Helyx modules. Duplicate command names and component IDs fail before the bot logs in.
 
+`HELYX_GLOBAL_COMMAND_MODE` defaults to `legacy`, preserving customer globals
+for production and self-hosted deployments during migration. Use
+`platform-only` only for an approved clean-slate pilot or final cutover; in
+that mode startup publishes only platform globals and migrated customer
+commands come from each guild's command profile and enabled module state.
+
 The built-in global `/helyx` and `/permissions` commands are core infrastructure. `/helyx` gives server owners, administrators and members with Manage Server permission an ephemeral module-management flow. It lists installed feature packages, enables or disables them, stages schema-defined settings, uses native Discord channel and role selectors, validates the complete configuration, and saves through the same versioned configuration and audit services as the dashboard. Dependency rules prevent a required module being disabled or a dependent module being enabled out of order.
 
 `/permissions` uses an owner/administrator-protected select and modal flow with native Discord selectors to manage inherited module policies and command overrides. Feature packages require an explicit allowlist: hosted distributions carry a reviewed `hosted-modules.json` catalogue, generated self-host projects use `HELYX_MODULE_CATALOGUE_PATH`, and `HELYX_MODULE_PACKAGES` remains an intentional comma-separated override. The sources are merged and de-duplicated. A core distribution has no catalogue and runs core-only when both self-host selectors are empty.
 
-Newly discovered feature modules are disabled for each Discord server by default. Global commands remain registered so Discord can present the installed Helyx command catalogue, but attempts to use a disabled module receive an ephemeral explanation directing the member to `/helyx` or the dashboard. Package upgrades preserve each server's existing enabled or disabled state.
+Newly discovered feature modules are disabled for each Discord server by
+default. In legacy mode their global commands remain registered, but attempts
+to use a disabled module receive an ephemeral explanation directing the member
+to `/helyx` or the dashboard. In platform-only mode, migrated commands are
+included in a guild only when its command profile selects them. Package
+upgrades preserve each server's existing enabled or disabled state.
 
 Gateway intents are derived from installed event contributions. The bot always requests Guilds, adds non-privileged reaction access only for reaction modules, and adds the privileged Server Members intent only when an installed module handles member joins. Deployments containing such a module must enable the matching intent in the Discord Developer Portal before startup.
 

package/dist/cloud-management-module.js

@@ -9,6 +9,7 @@ const DISCONNECT_CONFIRM_FIELD_ID = "helyx.cloud.disconnect.confirm";
 const ROTATE_MODAL_ID = "helyx.cloud.rotate";
 const ROTATE_CONFIRM_FIELD_ID = "helyx.cloud.rotate.confirm";
 const SUPPORT_MODAL_ID = "helyx.cloud.support";
+const SUPPORT_OPEN_MODAL_ID = "helyx.cloud.support.open";
 const SUPPORT_ENABLED_FIELD_ID = "helyx.cloud.support.enabled";
 const SUPPORT_DATA_FIELD_ID = "helyx.cloud.support.data";
 const DIAGNOSTICS_ENABLED_FIELD_ID = "helyx.cloud.support.diagnostics";
@@ -53,6 +54,7 @@ function discordOwnerIds(owner) {
 }
 export function createCloudManagementModule(input) {
     const ownerAuthorizer = new DeploymentOwnerAuthorizer(input.discord ?? new ClientCloudDiscordDirectory(input.client), input.configuredOwnerUserIds);
+    const preparedSupportModals = new Map();
     let ownerRefreshInterval;
     let onClientReady;
     const requireOwner = async (context) => {
@@ -83,7 +85,16 @@ export function createCloudManagementModule(input) {
             framework: "^0.1.0",
             dependencies: [],
             permissions: [],
-            contributions: { commands: ["helyx-cloud"], events: [] },
+            contributions: {
+                commands: [
+                    "helyx.cloud.connect",
+                    "helyx.cloud.status",
+                    "helyx.cloud.disconnect",
+                    "helyx.cloud.rotate",
+                    "helyx.cloud.support",
+                ],
+                events: [],
+            },
         },
         defaultPermissions: {
             module: restrictedPolicy(),
@@ -95,220 +106,278 @@ export function createCloudManagementModule(input) {
                 "helyx-cloud.support": restrictedPolicy(),
             },
         },
-        interactions: {
-            commands: [
-                {
-                    name: "helyx-cloud",
-                    description: "Manage this self-hosted bot's Helyx Cloud connection",
-                    registration: "global",
-                    contexts: ["guild", "bot_dm"],
-                    integrationTypes: ["guild_install"],
-                    subcommands: [
-                        {
-                            name: "connect",
-                            description: "Connect this deployment using a one-use code",
-                            acknowledgement: "immediate-modal",
-                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
-                            async execute(context) {
-                                if (!(await requireOwner(context)))
-                                    return;
-                                await context.showModal({
-                                    customId: CONNECT_MODAL_ID,
-                                    title: "Connect to Helyx Cloud",
-                                    text: [
-                                        {
-                                            content: "Create a short-lived connection code in `app.helyx.gg`, then paste it below. The code is used once and is not stored.",
-                                        },
-                                    ],
-                                    fields: [
-                                        {
-                                            customId: CONNECT_CODE_FIELD_ID,
-                                            label: "Cloud Connect code",
-                                            description: "Five groups of four letters and numbers.",
-                                            style: "short",
-                                            required: true,
-                                            minLength: 24,
-                                            maxLength: 24,
-                                            placeholder: "ABCD-EFGH-JKLM-NPQR-STUV",
-                                        },
-                                    ],
-                                });
+        sharedCommands: [
+            {
+                family: "helyx",
+                path: "cloud.connect",
+                contexts: ["guild", "bot_dm"],
+                permissionId: "helyx-cloud.connect",
+                description: "Connect this deployment using a one-use code",
+                acknowledgement: "immediate-modal",
+                authorization: "self-authorized",
+                rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                async execute(context) {
+                    if (!(await requireOwner(context)))
+                        return;
+                    await context.showModal({
+                        customId: CONNECT_MODAL_ID,
+                        title: "Connect to Helyx Cloud",
+                        text: [
+                            {
+                                content: "Create a short-lived connection code in `app.helyx.gg`, then paste it below. The code is used once and is not stored.",
                             },
-                        },
-                        {
-                            name: "status",
-                            description: "Show this deployment's Cloud Connect status",
-                            acknowledgement: "deferred-ephemeral",
-                            rateLimit: { scope: "user", limit: 20, windowSeconds: 60 },
-                            async execute(context) {
-                                if (!(await requireOwner(context)))
-                                    return;
-                                await context.reply(statusResponse(input.connector.status()));
+                        ],
+                        fields: [
+                            {
+                                customId: CONNECT_CODE_FIELD_ID,
+                                label: "Cloud Connect code",
+                                description: "Five groups of four letters and numbers.",
+                                style: "short",
+                                required: true,
+                                minLength: 24,
+                                maxLength: 24,
+                                placeholder: "ABCD-EFGH-JKLM-NPQR-STUV",
                             },
-                        },
-                        {
-                            name: "disconnect",
-                            description: "Revoke this deployment's Cloud Connect identity",
-                            acknowledgement: "immediate-modal",
-                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
-                            async execute(context) {
-                                if (!(await requireOwner(context)))
-                                    return;
-                                await context.showModal({
-                                    customId: DISCONNECT_MODAL_ID,
-                                    title: "Disconnect Helyx Cloud",
-                                    text: [
-                                        {
-                                            content: "This revokes the saved connector identity. A new dashboard code will be required to reconnect.",
-                                        },
-                                    ],
-                                    fields: [
-                                        {
-                                            type: "string-select",
-                                            customId: DISCONNECT_CONFIRM_FIELD_ID,
-                                            label: "Confirm disconnection",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: [
-                                                {
-                                                    label: "Keep Cloud Connect",
-                                                    value: "keep",
-                                                    default: true,
-                                                },
-                                                {
-                                                    label: "Disconnect and revoke",
-                                                    value: "disconnect",
-                                                },
-                                            ],
-                                        },
-                                    ],
-                                });
+                        ],
+                    });
+                },
+            },
+            {
+                family: "helyx",
+                path: "cloud.status",
+                contexts: ["guild", "bot_dm"],
+                permissionId: "helyx-cloud.status",
+                description: "Show this deployment's Cloud Connect status",
+                acknowledgement: "immediate-response",
+                authorization: "self-authorized",
+                async execute(context) {
+                    if (!(await requireOwner(context)))
+                        return;
+                    await context.reply(statusResponse(input.connector.status()));
+                },
+            },
+            {
+                family: "helyx",
+                path: "cloud.disconnect",
+                contexts: ["guild", "bot_dm"],
+                permissionId: "helyx-cloud.disconnect",
+                description: "Revoke this deployment's Cloud Connect identity",
+                acknowledgement: "immediate-modal",
+                authorization: "self-authorized",
+                rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                async execute(context) {
+                    if (!(await requireOwner(context)))
+                        return;
+                    await context.showModal({
+                        customId: DISCONNECT_MODAL_ID,
+                        title: "Disconnect Helyx Cloud",
+                        text: [
+                            {
+                                content: "This revokes the saved connector identity. A new dashboard code will be required to reconnect.",
                             },
-                        },
-                        {
-                            name: "rotate",
-                            description: "Replace the saved Cloud Connect credential",
-                            acknowledgement: "immediate-modal",
-                            rateLimit: { scope: "user", limit: 3, windowSeconds: 60 },
-                            async execute(context) {
-                                if (!(await requireOwner(context)))
-                                    return;
-                                await context.showModal({
-                                    customId: ROTATE_MODAL_ID,
-                                    title: "Rotate Cloud credential",
-                                    text: [
-                                        {
-                                            content: "Rotation replaces the encrypted connector key and immediately reconnects the bot. Local Discord features keep running.",
-                                        },
-                                    ],
-                                    fields: [
-                                        {
-                                            type: "string-select",
-                                            customId: ROTATE_CONFIRM_FIELD_ID,
-                                            label: "Confirm credential rotation",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: [
-                                                {
-                                                    label: "Cancel",
-                                                    value: "cancel",
-                                                    default: true,
-                                                },
-                                                {
-                                                    label: "Rotate credential",
-                                                    value: "rotate",
-                                                },
-                                            ],
-                                        },
-                                    ],
-                                });
+                        ],
+                        fields: [
+                            {
+                                type: "string-select",
+                                customId: DISCONNECT_CONFIRM_FIELD_ID,
+                                label: "Confirm disconnection",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: [
+                                    {
+                                        label: "Keep Cloud Connect",
+                                        value: "keep",
+                                        default: true,
+                                    },
+                                    {
+                                        label: "Disconnect and revoke",
+                                        value: "disconnect",
+                                    },
+                                ],
+                            },
+                        ],
+                    });
+                },
+            },
+            {
+                family: "helyx",
+                path: "cloud.rotate",
+                contexts: ["guild", "bot_dm"],
+                permissionId: "helyx-cloud.rotate",
+                description: "Replace the saved Cloud Connect credential",
+                acknowledgement: "immediate-modal",
+                authorization: "self-authorized",
+                rateLimit: { scope: "user", limit: 3, windowSeconds: 60 },
+                async execute(context) {
+                    if (!(await requireOwner(context)))
+                        return;
+                    await context.showModal({
+                        customId: ROTATE_MODAL_ID,
+                        title: "Rotate Cloud credential",
+                        text: [
+                            {
+                                content: "Rotation replaces the encrypted connector key and immediately reconnects the bot. Local Discord features keep running.",
                             },
+                        ],
+                        fields: [
+                            {
+                                type: "string-select",
+                                customId: ROTATE_CONFIRM_FIELD_ID,
+                                label: "Confirm credential rotation",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: [
+                                    {
+                                        label: "Cancel",
+                                        value: "cancel",
+                                        default: true,
+                                    },
+                                    {
+                                        label: "Rotate credential",
+                                        value: "rotate",
+                                    },
+                                ],
+                            },
+                        ],
+                    });
+                },
+            },
+            {
+                family: "helyx",
+                path: "cloud.support",
+                contexts: ["guild", "bot_dm"],
+                permissionId: "helyx-cloud.support",
+                description: "Choose what Helyx support may inspect",
+                acknowledgement: "deferred-ephemeral",
+                authorization: "self-authorized",
+                rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                async execute(context) {
+                    if (!(await requireOwner(context)))
+                        return;
+                    const consent = await input.connector.getSupportConsent();
+                    const definition = {
+                        customId: SUPPORT_MODAL_ID,
+                        title: "Cloud support access",
+                        text: [
+                            {
+                                content: "Support inspection is off by default. Submitted message content, secrets and arbitrary logs are never included.",
+                            },
+                        ],
+                        fields: [
+                            {
+                                type: "string-select",
+                                customId: SUPPORT_ENABLED_FIELD_ID,
+                                label: "Allow bounded support inspection",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: [
+                                    {
+                                        label: "No",
+                                        value: "no",
+                                        default: !consent.supportInspectionEnabled,
+                                    },
+                                    {
+                                        label: "Yes",
+                                        value: "yes",
+                                        default: consent.supportInspectionEnabled,
+                                    },
+                                ],
+                            },
+                            {
+                                type: "string-select",
+                                customId: SUPPORT_DATA_FIELD_ID,
+                                label: "Allowed support data",
+                                description: "Select only the bounded metadata support may inspect.",
+                                required: false,
+                                minValues: 0,
+                                maxValues: 5,
+                                options: [
+                                    ["Module inventory", "module_inventory"],
+                                    ["Redacted configuration", "configuration"],
+                                    ["Permission summaries", "permissions"],
+                                    ["Logging policy", "logging"],
+                                    ["Connector health", "health"],
+                                ].map(([label, value]) => ({
+                                    label,
+                                    value,
+                                    default: consent.supportDataClasses.includes(value),
+                                })),
+                            },
+                            {
+                                type: "string-select",
+                                customId: DIAGNOSTICS_ENABLED_FIELD_ID,
+                                label: "Allow bounded diagnostics",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: [
+                                    {
+                                        label: "No",
+                                        value: "no",
+                                        default: !consent.diagnosticsEnabled,
+                                    },
+                                    {
+                                        label: "Yes",
+                                        value: "yes",
+                                        default: consent.diagnosticsEnabled,
+                                    },
+                                ],
+                            },
+                        ],
+                    };
+                    preparedSupportModals.set(context.userId, {
+                        definition,
+                        expiresAt: Date.now() + 2 * 60 * 1_000,
+                    });
+                    await context.reply({
+                        ephemeral: true,
+                        componentsV2: {
+                            text: [
+                                {
+                                    content: "Your current support settings are ready. Open the form to review or change them.",
+                                },
+                            ],
                         },
-                        {
-                            name: "support",
-                            description: "Choose what Helyx support may inspect",
-                            acknowledgement: "immediate-modal",
-                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
-                            async execute(context) {
-                                if (!(await requireOwner(context)))
-                                    return;
-                                const consent = await input.connector.getSupportConsent();
-                                await context.showModal({
-                                    customId: SUPPORT_MODAL_ID,
-                                    title: "Cloud support access",
+                        buttons: [
+                            {
+                                type: "button",
+                                customId: SUPPORT_OPEN_MODAL_ID,
+                                label: "Open support settings",
+                                style: "primary",
+                            },
+                        ],
+                    });
+                },
+            },
+        ],
+        interactions: {
+            buttons: [
+                {
+                    customId: SUPPORT_OPEN_MODAL_ID,
+                    authorization: "public",
+                    async execute(context) {
+                        if (!(await requireOwner(context)))
+                            return;
+                        const prepared = preparedSupportModals.get(context.userId);
+                        preparedSupportModals.delete(context.userId);
+                        if (!prepared || prepared.expiresAt <= Date.now()) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
                                     text: [
                                         {
-                                            content: "Support inspection is off by default. Submitted message content, secrets and arbitrary logs are never included.",
-                                        },
-                                    ],
-                                    fields: [
-                                        {
-                                            type: "string-select",
-                                            customId: SUPPORT_ENABLED_FIELD_ID,
-                                            label: "Allow bounded support inspection",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: [
-                                                {
-                                                    label: "No",
-                                                    value: "no",
-                                                    default: !consent.supportInspectionEnabled,
-                                                },
-                                                {
-                                                    label: "Yes",
-                                                    value: "yes",
-                                                    default: consent.supportInspectionEnabled,
-                                                },
-                                            ],
-                                        },
-                                        {
-                                            type: "string-select",
-                                            customId: SUPPORT_DATA_FIELD_ID,
-                                            label: "Allowed support data",
-                                            description: "Select only the bounded metadata support may inspect.",
-                                            required: false,
-                                            minValues: 0,
-                                            maxValues: 5,
-                                            options: [
-                                                ["Module inventory", "module_inventory"],
-                                                ["Redacted configuration", "configuration"],
-                                                ["Permission summaries", "permissions"],
-                                                ["Logging policy", "logging"],
-                                                ["Connector health", "health"],
-                                            ].map(([label, value]) => ({
-                                                label,
-                                                value,
-                                                default: consent.supportDataClasses.includes(value),
-                                            })),
-                                        },
-                                        {
-                                            type: "string-select",
-                                            customId: DIAGNOSTICS_ENABLED_FIELD_ID,
-                                            label: "Allow bounded diagnostics",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: [
-                                                {
-                                                    label: "No",
-                                                    value: "no",
-                                                    default: !consent.diagnosticsEnabled,
-                                                },
-                                                {
-                                                    label: "Yes",
-                                                    value: "yes",
-                                                    default: consent.diagnosticsEnabled,
-                                                },
-                                            ],
+                                            content: "This support form expired. Run `/helyx cloud support` again.",
                                         },
                                     ],
-                                });
-                            },
-                        },
-                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.showModal(prepared.definition);
+                    },
                 },
             ],
             modals: [

package/dist/command-registration-policy.d.ts

@@ -0,0 +1,8 @@
+import type { CommandContribution, CommandRegistrationPolicy, ModuleDefinition } from "@helyx/sdk";
+export type ModuleCommandRegistrationPolicy = CommandRegistrationPolicy | "none";
+export type GlobalCommandRegistrationMode = "legacy" | "platform-only";
+export declare function commandRegistrationPolicy(module: ModuleDefinition): ModuleCommandRegistrationPolicy;
+export declare function contributionRegistrationPolicy(module: ModuleDefinition, contribution: CommandContribution, options: {
+    allowLegacyCustomerGlobals: boolean;
+}): ModuleCommandRegistrationPolicy;
+//# sourceMappingURL=command-registration-policy.d.ts.map

package/dist/command-registration-policy.js

@@ -0,0 +1,39 @@
+import { isCustomerSelectableModule } from "@helyx/module-manifest";
+const platformGlobalModuleIds = new Set([
+    "helyx.management",
+    "helyx.support",
+    "helyx.oauth",
+    "helyx.permissions",
+    "helyx.privacy",
+]);
+const deploymentModuleIds = new Set(["helyx.cloud-connect"]);
+const internalGuildModuleIds = new Set(["helyx.developer-operations"]);
+export function commandRegistrationPolicy(module) {
+    if (platformGlobalModuleIds.has(module.manifest.id))
+        return "platform-global";
+    if (deploymentModuleIds.has(module.manifest.id))
+        return "deployment";
+    if (internalGuildModuleIds.has(module.manifest.id))
+        return "internal-guild";
+    if (!isCustomerSelectableModule(module.manifest))
+        return "none";
+    return hasCommands(module) ? "enabled-guild" : "none";
+}
+export function contributionRegistrationPolicy(module, contribution, options) {
+    if (contribution.registrationPolicy)
+        return contribution.registrationPolicy;
+    const modulePolicy = commandRegistrationPolicy(module);
+    if (modulePolicy !== "enabled-guild")
+        return modulePolicy;
+    if (!options.allowLegacyCustomerGlobals)
+        return "none";
+    return contribution.registration === "guild"
+        ? "internal-guild"
+        : "platform-global";
+}
+function hasCommands(module) {
+    return Boolean(module.interactions?.commands?.length ||
+        module.sharedCommands?.length ||
+        module.nexusCommands?.length);
+}
+//# sourceMappingURL=command-registration-policy.js.map