@helyx/bot 0.4.44 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- bbc4eee: Add the shared exact-progress, zoned-time, ordered-retention, multi-schedule, and durable cross-module role-ownership contracts required by the Events and Community Goals Testing modules.
+
+  Register the PostgreSQL progress and ownership services in core, deliver owned roles through bot roots and shard workers, and package the corresponding database migration and rollback.
+
+### Patch Changes
+
+- Updated dependencies [bbc4eee]
+- Updated dependencies
+  - @helyx/sdk@0.10.0
+  - @helyx/platform@0.7.0
+  - @helyx/database@0.10.0
+
+## 0.4.48
+
+### Patch Changes
+
+- Add declared command-operation permission targets, project them through both permission-management surfaces, and harden module lifecycle, health, visibility, bounded-work, optional-side-effect, command-permission, and Forms durable-workflow behavior. Preserve existing FAQ, Access Control, Achievements, Giveaways and Levels overrides through additive migrations while assigning every slash-command path its own permission identity.
+
+## 0.4.47
+
+### Patch Changes
+
+- Add the bounded Discord inspection, durable record scheduling and recurrence, trusted dashboard workspaces, rich-message composition, optional invite-attribution contracts, module deactivation/configuration hooks, and versioned schedulable-action registry required by the Analytics, Invite Tracking, Reminders, Birthdays, Role Expiry, Scheduler, Message Embedder, Auto-message, and Sticky Messages testing modules.
+
+## 0.4.46
+
+### Patch Changes
+
+- Add explicit role-mention allowlists and member-leave identity metadata to the
+  module runtime contract. Upgrade Welcome with multiline user, role and channel
+  placeholders, an inline dashboard test send, and independent member-left
+  logging.
+
+## 0.4.45
+
+### Patch Changes
+
+- Expose bounded structural user mentions to guild message event contributions without exposing message content, and include AFK in the reviewed self-host catalogue.
+
 ## 0.4.44
 
 ### Patch Changes

package/dist/command-path-contract.d.ts

@@ -0,0 +1,26 @@
+import type { CommandContribution, ModuleDefinition, SubcommandContribution } from "@helyx/sdk";
+export interface ExecutableCommandPath {
+    path: string;
+    permissionId: string;
+    explicitPermissionId: boolean;
+    name: string;
+    description: string;
+    source: "direct" | "shared" | "nexus";
+}
+export interface CommandPermissionTarget {
+    id: string;
+    name: string;
+    description: string;
+    kind: "command" | "operation";
+}
+export interface CommandPathContractIssue {
+    key: string;
+    message: string;
+}
+export declare const legacyCommandPathContractIssues: Readonly<Record<string, ReadonlySet<string>>>;
+export declare function collectExecutableCommandPaths(module: ModuleDefinition): ExecutableCommandPath[];
+export declare function collectCommandPermissionTargets(module: ModuleDefinition): CommandPermissionTarget[];
+export declare function resolveDirectCommandPath(command: CommandContribution, subcommand?: SubcommandContribution, groupName?: string | null): Pick<ExecutableCommandPath, "path" | "permissionId">;
+export declare function inspectCommandPathContract(module: ModuleDefinition): CommandPathContractIssue[];
+export declare function assertCommandPathContract(module: ModuleDefinition): void;
+//# sourceMappingURL=command-path-contract.d.ts.map

package/dist/command-path-contract.js

@@ -0,0 +1,157 @@
+export const legacyCommandPathContractIssues = Object.freeze({});
+export function collectExecutableCommandPaths(module) {
+    const paths = (module.interactions?.commands ?? []).flatMap((command) => collectDirectCommandPaths(command));
+    paths.push(...(module.sharedCommands ?? []).map((command) => {
+        const path = `${command.family}.${command.path}`;
+        return {
+            path,
+            permissionId: command.permissionId ?? path,
+            explicitPermissionId: command.permissionId !== undefined,
+            name: `/${command.family} ${command.path.replaceAll(".", " ")}`,
+            description: command.description,
+            source: "shared",
+        };
+    }), ...(module.nexusCommands ?? []).map((command) => {
+        const path = `nexus.${command.path}`;
+        return {
+            path,
+            permissionId: path,
+            explicitPermissionId: true,
+            name: `/nexus ${command.path.replaceAll(".", " ")}`,
+            description: command.description,
+            source: "nexus",
+        };
+    }));
+    return paths;
+}
+export function collectCommandPermissionTargets(module) {
+    return [
+        ...collectExecutableCommandPaths(module).map((command) => ({
+            id: command.permissionId,
+            name: command.name,
+            description: command.description,
+            kind: "command",
+        })),
+        ...(module.interactions?.commands ?? []).flatMap((command) => [
+            ...permissionOperations(command.permissionOperations),
+            ...(command.subcommands ?? []).flatMap((subcommand) => permissionOperations(subcommand.permissionOperations)),
+            ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.flatMap((subcommand) => permissionOperations(subcommand.permissionOperations))),
+        ]),
+        ...(module.sharedCommands ?? []).flatMap((command) => permissionOperations(command.permissionOperations)),
+        ...(module.nexusCommands ?? []).flatMap((command) => permissionOperations(command.permissionOperations)),
+    ];
+}
+export function resolveDirectCommandPath(command, subcommand, groupName) {
+    const path = [command.name, groupName, subcommand?.name]
+        .filter(Boolean)
+        .join(".");
+    return {
+        path,
+        permissionId: subcommand?.permissionId ?? command.permissionId ?? path,
+    };
+}
+export function inspectCommandPathContract(module) {
+    const issues = [];
+    const paths = collectExecutableCommandPaths(module);
+    const operations = collectCommandPermissionTargets(module).filter(({ kind }) => kind === "operation");
+    const pathsByPermissionId = new Map();
+    const seenPaths = new Set();
+    for (const command of paths) {
+        if (seenPaths.has(command.path)) {
+            issues.push({
+                key: `duplicate-command-path:${command.path}`,
+                message: `duplicate executable command path ${command.path}`,
+            });
+        }
+        seenPaths.add(command.path);
+        if (!command.explicitPermissionId) {
+            issues.push({
+                key: `missing-permission-id:${command.path}`,
+                message: `command ${command.path} has no explicit permission ID`,
+            });
+            continue;
+        }
+        const owners = pathsByPermissionId.get(command.permissionId) ?? [];
+        pathsByPermissionId.set(command.permissionId, [...owners, command.path]);
+        if (!Object.prototype.hasOwnProperty.call(module.defaultPermissions?.commands ?? {}, command.permissionId)) {
+            issues.push({
+                key: `missing-default-policy:${command.path}`,
+                message: `command ${command.path} has no explicit default policy for ${command.permissionId}`,
+            });
+        }
+    }
+    for (const operation of operations) {
+        if (operation.id.trim().length === 0 ||
+            operation.id.length > 100 ||
+            !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u.test(operation.id) ||
+            operation.name.trim().length === 0 ||
+            operation.name.length > 100 ||
+            operation.description.trim().length === 0) {
+            issues.push({
+                key: `invalid-permission-operation:${operation.id}`,
+                message: "command permission operations require a namespaced ID and a non-empty Discord-safe name and description",
+            });
+            continue;
+        }
+        const owners = pathsByPermissionId.get(operation.id) ?? [];
+        pathsByPermissionId.set(operation.id, [
+            ...owners,
+            `operation:${operation.name}`,
+        ]);
+        if (!Object.prototype.hasOwnProperty.call(module.defaultPermissions?.commands ?? {}, operation.id)) {
+            issues.push({
+                key: `missing-default-policy:operation:${operation.id}`,
+                message: `command operation ${operation.name} has no explicit default policy for ${operation.id}`,
+            });
+        }
+    }
+    for (const [permissionId, owners] of pathsByPermissionId) {
+        if (owners.length > 1) {
+            issues.push({
+                key: `duplicate-permission-id:${permissionId}`,
+                message: `permission ID ${permissionId} is shared by ${owners.join(", ")}`,
+            });
+        }
+    }
+    return issues.sort((left, right) => left.key.localeCompare(right.key, "en-GB"));
+}
+function permissionOperations(operations) {
+    return (operations ?? []).map((operation) => ({
+        ...operation,
+        kind: "operation",
+    }));
+}
+export function assertCommandPathContract(module) {
+    const issues = inspectCommandPathContract(module);
+    const actual = new Set(issues.map(({ key }) => key));
+    const expected = legacyCommandPathContractIssues[module.manifest.id] ?? new Set();
+    const unexpected = issues.filter(({ key }) => !expected.has(key));
+    const stale = [...expected].filter((key) => !actual.has(key));
+    if (unexpected.length === 0 && stale.length === 0)
+        return;
+    const details = [
+        ...unexpected.map(({ message }) => message),
+        ...stale.map((key) => `legacy command-path exception is no longer needed: ${key}`),
+    ];
+    throw new Error(`Module ${module.manifest.id} command-path contract failed:\n${details.join("\n")}`);
+}
+function collectDirectCommandPaths(command) {
+    const nested = [
+        ...(command.subcommands ?? []).map((subcommand) => directCommandPath(command, subcommand)),
+        ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.map((subcommand) => directCommandPath(command, subcommand, group.name))),
+    ];
+    if (nested.length > 0 || !command.execute)
+        return nested;
+    return [directCommandPath(command)];
+}
+function directCommandPath(command, subcommand, groupName) {
+    const resolved = resolveDirectCommandPath(command, subcommand, groupName);
+    return {
+        ...resolved,
+        explicitPermissionId: (subcommand?.permissionId ?? command.permissionId) !== undefined,
+        name: `/${resolved.path.replaceAll(".", " ")}`,
+        description: subcommand?.description ?? command.description,
+        source: "direct",
+    };
+}
+//# sourceMappingURL=command-path-contract.js.map

package/dist/control-permissions.js

@@ -9,6 +9,7 @@ export function dashboardActionPermissionId(module, actionId) {
     return selectDeclaredPermission(module, [
         `${namespace}.${actionId.replaceAll("-", ".")}`,
         `${namespace}.configure`,
+        `${namespace}.manage`,
     ]);
 }
 export function managedResourcePermissionId(module, resourceType, operation, actionId, declaredPermissionId) {

package/dist/control-server.d.ts

@@ -51,7 +51,7 @@ export interface BotControlGuildResources {
     channels: Array<{
         id: string;
         name: string;
-        type: "guild_text" | "guild_announcement" | "guild_category";
+        type: "guild_text" | "guild_announcement" | "guild_category" | "guild_forum" | "guild_media";
     }>;
     roles: Array<{
         id: string;

package/dist/control-server.js

@@ -147,7 +147,9 @@ export class DiscordGuildResourceDirectory {
                 channels: [...channels.values()]
                     .filter((channel) => channel?.type === ChannelType.GuildText ||
                     channel?.type === ChannelType.GuildAnnouncement ||
-                    channel?.type === ChannelType.GuildCategory)
+                    channel?.type === ChannelType.GuildCategory ||
+                    channel?.type === ChannelType.GuildForum ||
+                    channel?.type === ChannelType.GuildMedia)
                     .map((channel) => ({
                     id: channel.id,
                     name: channel.name,
@@ -155,7 +157,11 @@ export class DiscordGuildResourceDirectory {
                         ? "guild_announcement"
                         : channel.type === ChannelType.GuildCategory
                             ? "guild_category"
-                            : "guild_text",
+                            : channel.type === ChannelType.GuildForum
+                                ? "guild_forum"
+                                : channel.type === ChannelType.GuildMedia
+                                    ? "guild_media"
+                                    : "guild_text",
                 }))
                     .sort((left, right) => left.name.localeCompare(right.name)),
                 roles: [...roles.values()]

package/dist/dashboard-commands.js

@@ -1,41 +1,11 @@
 import { emptyPolicy, toDashboardPolicy, } from "./control-permissions.js";
+import { collectCommandPermissionTargets } from "./command-path-contract.js";
 export function dashboardCommands(module) {
-    const commands = (module.interactions?.commands ?? []).flatMap((command) => {
-        const nested = [
-            ...(command.subcommands ?? []).map((subcommand) => dashboardCommand(module, {
-                id: subcommand.permissionId ??
-                    command.permissionId ??
-                    `${command.name}.${subcommand.name}`,
-                name: `/${command.name} ${subcommand.name}`,
-                description: subcommand.description,
-            })),
-            ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.map((subcommand) => dashboardCommand(module, {
-                id: subcommand.permissionId ??
-                    command.permissionId ??
-                    `${command.name}.${group.name}.${subcommand.name}`,
-                name: `/${command.name} ${group.name} ${subcommand.name}`,
-                description: subcommand.description,
-            }))),
-        ];
-        if (nested.length > 0)
-            return nested;
-        return [
-            dashboardCommand(module, {
-                id: command.permissionId ?? command.name,
-                name: `/${command.name}`,
-                description: command.description,
-            }),
-        ];
-    });
-    commands.push(...(module.sharedCommands ?? []).map((command) => dashboardCommand(module, {
-        id: command.permissionId ?? `${command.family}.${command.path}`,
-        name: `/${command.family} ${command.path.replace(".", " ")}`,
+    const commands = collectCommandPermissionTargets(module).map((command) => dashboardCommand(module, {
+        id: command.id,
+        name: command.name,
         description: command.description,
-    })), ...(module.nexusCommands ?? []).map((command) => dashboardCommand(module, {
-        id: `nexus.${command.path}`,
-        name: `/nexus ${command.path.replace(".", " ")}`,
-        description: command.description,
-    })));
+    }));
     return [
         ...new Map(commands.map((command) => [command.id, command])).values(),
     ];

package/dist/discord-analytics.d.ts

@@ -0,0 +1,30 @@
+import type { DiscordAnalyticsInspectionService } from "@helyx/sdk";
+import { type Client } from "discord.js";
+export declare class DiscordAnalyticsInspection implements DiscordAnalyticsInspectionService {
+    private readonly client;
+    constructor(client: Client);
+    listChannels(input: {
+        guildId: string;
+        roleId?: string;
+    }): ReturnType<DiscordAnalyticsInspectionService["listChannels"]>;
+    listMessages(input: {
+        guildId: string;
+        channelId: string;
+        before?: string;
+        limit: number;
+    }): ReturnType<DiscordAnalyticsInspectionService["listMessages"]>;
+    listMembers(input: {
+        guildId: string;
+        after?: string;
+        limit: number;
+    }): ReturnType<DiscordAnalyticsInspectionService["listMembers"]>;
+    listThreads(input: {
+        guildId: string;
+        parentChannelId?: string;
+        cursor?: string;
+        limit: number;
+        includeArchived: boolean;
+        includePrivate: boolean;
+    }): ReturnType<DiscordAnalyticsInspectionService["listThreads"]>;
+}
+//# sourceMappingURL=discord-analytics.d.ts.map