@helyx/bot 0.1.0

package/dist/permissions-module.js

@@ -0,0 +1,497 @@
+import { defineModule, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { PermissionFlagsBits } from "discord.js";
+const MODULE_SELECT_ID = "helyx.permissions.module";
+const TARGET_SELECT_ID = "helyx.permissions.target";
+const MODULE_PREVIOUS_ID = "helyx.permissions.module.previous";
+const MODULE_NEXT_ID = "helyx.permissions.module.next";
+const TARGET_PREVIOUS_ID = "helyx.permissions.target.previous";
+const TARGET_NEXT_ID = "helyx.permissions.target.next";
+const POLICY_MODAL_ID = "helyx.permissions.policy";
+const EVERYONE_FIELD_ID = "helyx.permissions.policy.everyone";
+const REQUIRED_PERMISSIONS_FIELD_ID = "helyx.permissions.policy.required";
+const ALLOWED_MENTIONABLES_FIELD_ID = "helyx.permissions.policy.allowed";
+const DENIED_MENTIONABLES_FIELD_ID = "helyx.permissions.policy.denied";
+const SESSION_PURPOSE = "permissions.manage";
+const MODULE_PAGE_SIZE = 25;
+const TARGET_PAGE_SIZE = 24;
+const VIOLET = 0x7c3aed;
+export function createPermissionsModule(configurableModules) {
+    const modules = new Map(configurableModules.map((module) => [module.manifest.id, module]));
+    const commandModules = [...modules.values()]
+        .filter((module) => commandTargets(module).length > 0)
+        .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
+    return defineModule({
+        manifest: {
+            manifestVersion: "0.1",
+            id: "helyx.permissions",
+            name: "Permissions",
+            version: "0.1.0",
+            description: "Configures Helyx module and command access policies.",
+            entry: "./dist/permissions-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["permissions"], events: [] },
+        },
+        defaultPermissions: {
+            module: restrictedPolicy(),
+            commands: {
+                permissions: restrictedPolicy(),
+            },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "permissions",
+                    description: "Configure access to Helyx modules and commands",
+                    registration: "global",
+                    contexts: ["guild"],
+                    integrationTypes: ["guild_install"],
+                    rateLimit: { scope: "user", limit: 20, windowSeconds: 60 },
+                    async execute(context) {
+                        if (!context.serverId)
+                            return;
+                        if (commandModules.length === 0) {
+                            await context.reply({
+                                ephemeral: true,
+                                embed: {
+                                    title: "No configurable modules",
+                                    description: "Install a feature module that contributes Discord commands first.",
+                                    color: 0xdc2626,
+                                },
+                            });
+                            return;
+                        }
+                        await context.services
+                            .get(HELYX_SERVICE_NAMES.sessions)
+                            .create({
+                            guildId: context.serverId,
+                            userId: context.userId,
+                            purpose: SESSION_PURPOSE,
+                            state: { modulePage: 0 },
+                            expiresAt: new Date(Date.now() + 10 * 60 * 1_000),
+                            replace: true,
+                        });
+                        await context.reply(modulePickerResponse(commandModules, 0));
+                    },
+                },
+            ],
+            selects: [
+                {
+                    customId: MODULE_SELECT_ID,
+                    async execute(context) {
+                        const session = await getSession(context);
+                        if (!session || !context.serverId)
+                            return;
+                        const moduleId = context.selectedValues[0];
+                        const module = moduleId
+                            ? commandModules.find((candidate) => candidate.manifest.id === moduleId)
+                            : undefined;
+                        if (!module)
+                            throw new Error("Selected module is unavailable");
+                        const targets = commandTargets(module);
+                        await context.services
+                            .get(HELYX_SERVICE_NAMES.sessions)
+                            .update({
+                            sessionId: session.sessionId,
+                            state: {
+                                ...session.state,
+                                moduleId,
+                                targetPage: 0,
+                            },
+                            expectedVersion: session.version,
+                        });
+                        await context.reply(targetPickerResponse(module, targets, 0));
+                    },
+                },
+                {
+                    customId: TARGET_SELECT_ID,
+                    async execute(context) {
+                        const session = await getSession(context);
+                        if (!session || !context.serverId)
+                            return;
+                        const moduleId = stringState(session.state, "moduleId");
+                        const target = context.selectedValues[0];
+                        const module = modules.get(moduleId);
+                        if (!module || !target)
+                            throw new Error("Permission target expired");
+                        const commandId = target === "__module__" ? undefined : target;
+                        if (commandId && !commandTargets(module).includes(commandId)) {
+                            throw new Error("Selected command is unavailable");
+                        }
+                        const current = await context.services
+                            .get(HELYX_SERVICE_NAMES.permissions)
+                            .getPolicy(context.serverId, moduleId, commandId);
+                        const allowedDefaults = mentionableDefaults(current.policy.allowedUserIds, current.policy.allowedRoleIds);
+                        const deniedDefaults = mentionableDefaults(current.policy.deniedUserIds, current.policy.deniedRoleIds);
+                        if (allowedDefaults.length > 25 || deniedDefaults.length > 25) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    accentColor: 0xdc2626,
+                                    text: [
+                                        {
+                                            content: "## Policy is too large for Discord\nA Discord modal can show at most 25 allowed and 25 denied users or roles. Use the Helyx dashboard to edit this policy without losing existing entries.",
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.services
+                            .get(HELYX_SERVICE_NAMES.sessions)
+                            .update({
+                            sessionId: session.sessionId,
+                            state: {
+                                moduleId,
+                                ...(commandId ? { commandId } : {}),
+                                expectedPolicyVersion: current.version?.toString() ?? null,
+                            },
+                            expectedVersion: session.version,
+                        });
+                        await context.showModal({
+                            customId: POLICY_MODAL_ID,
+                            title: "Edit permission policy",
+                            fields: [
+                                {
+                                    type: "string-select",
+                                    customId: EVERYONE_FIELD_ID,
+                                    label: "Allow everyone to use the command?",
+                                    description: "Overrides below still take priority over this setting.",
+                                    required: true,
+                                    minValues: 1,
+                                    maxValues: 1,
+                                    options: [
+                                        {
+                                            label: "Yes",
+                                            value: "yes",
+                                            default: current.policy.everyone,
+                                        },
+                                        {
+                                            label: "No",
+                                            value: "no",
+                                            default: !current.policy.everyone,
+                                        },
+                                    ],
+                                },
+                                {
+                                    customId: REQUIRED_PERMISSIONS_FIELD_ID,
+                                    label: "Required Discord permissions",
+                                    description: "Optional permission names; separate multiple values with commas.",
+                                    style: "paragraph",
+                                    value: current.policy.requiredPermissions.join(", "),
+                                    placeholder: "MANAGE_GUILD, MODERATE_MEMBERS",
+                                    maxLength: 1000,
+                                },
+                                {
+                                    type: "discord-mentionable",
+                                    customId: ALLOWED_MENTIONABLES_FIELD_ID,
+                                    label: "Allowed users and roles",
+                                    description: "Users override role denials; allowed roles bypass general rules.",
+                                    placeholder: "Choose allowed users and roles",
+                                    required: false,
+                                    minValues: 0,
+                                    maxValues: 25,
+                                    defaultValues: allowedDefaults,
+                                },
+                                {
+                                    type: "discord-mentionable",
+                                    customId: DENIED_MENTIONABLES_FIELD_ID,
+                                    label: "Denied users and roles",
+                                    description: "User denials take priority; role denials apply next.",
+                                    placeholder: "Choose denied users and roles",
+                                    required: false,
+                                    minValues: 0,
+                                    maxValues: 25,
+                                    defaultValues: deniedDefaults,
+                                },
+                            ],
+                        });
+                    },
+                },
+            ],
+            buttons: [
+                modulePageButton(MODULE_PREVIOUS_ID, -1),
+                modulePageButton(MODULE_NEXT_ID, 1),
+                targetPageButton(TARGET_PREVIOUS_ID, -1),
+                targetPageButton(TARGET_NEXT_ID, 1),
+            ],
+            modals: [
+                {
+                    customId: POLICY_MODAL_ID,
+                    async execute(context) {
+                        const session = await getSession(context);
+                        if (!session || !context.serverId)
+                            return;
+                        const moduleId = stringState(session.state, "moduleId");
+                        const commandId = optionalStringState(session.state, "commandId");
+                        const expected = session.state.expectedPolicyVersion;
+                        const everyoneValues = context.getStringSelectValues(EVERYONE_FIELD_ID);
+                        if (everyoneValues.length !== 1 ||
+                            !["yes", "no"].includes(everyoneValues[0])) {
+                            throw new Error("Allow everyone selection is invalid");
+                        }
+                        const allowed = context.getSelectedMentionables(ALLOWED_MENTIONABLES_FIELD_ID);
+                        const denied = context.getSelectedMentionables(DENIED_MENTIONABLES_FIELD_ID);
+                        assertNoMentionableConflicts(allowed, denied);
+                        const policy = {
+                            everyone: everyoneValues[0] === "yes",
+                            requiredPermissions: parsePermissions(context.getField(REQUIRED_PERMISSIONS_FIELD_ID)),
+                            allowedRoleIds: [...allowed.roleIds],
+                            deniedRoleIds: [...denied.roleIds],
+                            allowedUserIds: [...allowed.userIds],
+                            deniedUserIds: [...denied.userIds],
+                        };
+                        await context.services
+                            .get(HELYX_SERVICE_NAMES.permissions)
+                            .setPolicy({
+                            guildId: context.serverId,
+                            moduleId,
+                            ...(commandId ? { commandId } : {}),
+                            policy,
+                            expectedVersion: typeof expected === "string" ? BigInt(expected) : null,
+                            context: {
+                                actorUserId: context.userId,
+                                correlationId: context.interactionId,
+                                source: "discord",
+                            },
+                        });
+                        await context.services
+                            .get(HELYX_SERVICE_NAMES.sessions)
+                            .delete(session.sessionId);
+                        await context.reply({
+                            ephemeral: true,
+                            embed: {
+                                title: "Permissions updated",
+                                description: commandId
+                                    ? "The override for `" + commandId + "` was updated."
+                                    : "The module policy for `" + moduleId + "` was updated.",
+                                color: 0x16a34a,
+                            },
+                        });
+                    },
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    });
+    function modulePageButton(customId, change) {
+        return {
+            customId,
+            async execute(context) {
+                const session = await getSession(context);
+                if (!session)
+                    return;
+                const requested = numberState(session.state, "modulePage") + change;
+                const page = clampPage(requested, pageCount(commandModules.length, MODULE_PAGE_SIZE));
+                await context.services
+                    .get(HELYX_SERVICE_NAMES.sessions)
+                    .update({
+                    sessionId: session.sessionId,
+                    state: { ...session.state, modulePage: page },
+                    expectedVersion: session.version,
+                });
+                await context.reply(modulePickerResponse(commandModules, page));
+            },
+        };
+    }
+    function targetPageButton(customId, change) {
+        return {
+            customId,
+            async execute(context) {
+                const session = await getSession(context);
+                if (!session)
+                    return;
+                const moduleId = stringState(session.state, "moduleId");
+                const module = commandModules.find((candidate) => candidate.manifest.id === moduleId);
+                if (!module)
+                    throw new Error("Selected module is unavailable");
+                const targets = commandTargets(module);
+                const requested = numberState(session.state, "targetPage") + change;
+                const page = clampPage(requested, pageCount(targets.length, TARGET_PAGE_SIZE));
+                await context.services
+                    .get(HELYX_SERVICE_NAMES.sessions)
+                    .update({
+                    sessionId: session.sessionId,
+                    state: { ...session.state, targetPage: page },
+                    expectedVersion: session.version,
+                });
+                await context.reply(targetPickerResponse(module, targets, page));
+            },
+        };
+    }
+}
+function restrictedPolicy() {
+    return {
+        everyone: false,
+        requiredPermissions: ["MANAGE_GUILD"],
+        allowedRoleIds: [],
+        deniedRoleIds: [],
+        allowedUserIds: [],
+        deniedUserIds: [],
+    };
+}
+function commandTargets(module) {
+    return (module.interactions?.commands ?? []).flatMap((command) => command.subcommands?.length
+        ? command.subcommands.map((subcommand) => `${command.name}.${subcommand.name}`)
+        : [command.name]);
+}
+function modulePickerResponse(modules, requestedPage) {
+    const pages = pageCount(modules.length, MODULE_PAGE_SIZE);
+    const page = clampPage(requestedPage, pages);
+    const visible = pageItems(modules, page, MODULE_PAGE_SIZE);
+    return {
+        ephemeral: true,
+        embed: {
+            title: "Module permissions",
+            description: "Choose an installed module. Disabled modules can be configured before they are enabled. Module-level policy is inherited unless a command override exists." +
+                (pages > 1 ? ` Page ${String(page + 1)} of ${String(pages)}.` : ""),
+            color: VIOLET,
+        },
+        selects: [
+            {
+                customId: MODULE_SELECT_ID,
+                placeholder: "Choose a module",
+                options: visible.map((module) => ({
+                    label: module.manifest.name,
+                    value: module.manifest.id,
+                    description: module.manifest.description.slice(0, 100),
+                })),
+            },
+        ],
+        buttons: paginationButtons(page, pages, MODULE_PREVIOUS_ID, MODULE_NEXT_ID),
+    };
+}
+function targetPickerResponse(module, targets, requestedPage) {
+    const pages = pageCount(targets.length, TARGET_PAGE_SIZE);
+    const page = clampPage(requestedPage, pages);
+    const visible = pageItems(targets, page, TARGET_PAGE_SIZE);
+    return {
+        ephemeral: true,
+        embed: {
+            title: `${module.manifest.name} permissions`,
+            description: "Choose the whole module or one command. Command policies override the module policy." +
+                (pages > 1 ? ` Page ${String(page + 1)} of ${String(pages)}.` : ""),
+            color: VIOLET,
+        },
+        selects: [
+            {
+                customId: TARGET_SELECT_ID,
+                placeholder: "Choose a permission target",
+                options: [
+                    {
+                        label: "Entire module",
+                        value: "__module__",
+                        description: "Default policy for every command",
+                    },
+                    ...visible.map((target) => ({
+                        label: `/${target.replaceAll(".", " ")}`,
+                        value: target,
+                    })),
+                ],
+            },
+        ],
+        buttons: paginationButtons(page, pages, TARGET_PREVIOUS_ID, TARGET_NEXT_ID),
+    };
+}
+function paginationButtons(page, pages, previousId, nextId) {
+    return [
+        ...(page > 0
+            ? [
+                {
+                    type: "button",
+                    customId: previousId,
+                    label: "Previous page",
+                    style: "secondary",
+                },
+            ]
+            : []),
+        ...(page + 1 < pages
+            ? [
+                {
+                    type: "button",
+                    customId: nextId,
+                    label: "Next page",
+                    style: "secondary",
+                },
+            ]
+            : []),
+    ];
+}
+function pageItems(items, page, size) {
+    return items.slice(page * size, (page + 1) * size);
+}
+function pageCount(itemCount, size) {
+    return Math.max(1, Math.ceil(itemCount / size));
+}
+function clampPage(page, pages) {
+    return Math.max(0, Math.min(page, pages - 1));
+}
+async function getSession(context) {
+    if (!context.serverId)
+        return null;
+    const session = await context.services
+        .get(HELYX_SERVICE_NAMES.sessions)
+        .getFor(context.serverId, context.userId, SESSION_PURPOSE);
+    if (!session)
+        throw new Error("Permission session expired; run /permissions again");
+    return session;
+}
+function stringState(state, field) {
+    const value = state[field];
+    if (typeof value !== "string")
+        throw new Error("Permission session is invalid");
+    return value;
+}
+function numberState(state, field) {
+    const value = state[field];
+    if (value === undefined)
+        return 0;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error("Permission session is invalid");
+    }
+    return value;
+}
+function optionalStringState(state, field) {
+    const value = state[field];
+    return typeof value === "string" ? value : undefined;
+}
+function mentionableDefaults(userIds, roleIds) {
+    return [
+        ...userIds.map((id) => ({ type: "user", id })),
+        ...roleIds.map((id) => ({ type: "role", id })),
+    ];
+}
+function assertNoMentionableConflicts(allowed, denied) {
+    const deniedUsers = new Set(denied.userIds);
+    const deniedRoles = new Set(denied.roleIds);
+    if (allowed.userIds.some((id) => deniedUsers.has(id)) ||
+        allowed.roleIds.some((id) => deniedRoles.has(id))) {
+        throw new Error("A user or role cannot be both allowed and denied");
+    }
+}
+function parsePermissions(value) {
+    const permissions = splitValues(value).map((item) => item.toUpperCase());
+    for (const permission of permissions) {
+        if (!/^[A-Z][A-Z0-9_]*$/u.test(permission)) {
+            throw new Error(`Invalid Discord permission: ${permission}`);
+        }
+        const discordName = permission
+            .toLowerCase()
+            .split("_")
+            .map((part) => part[0]?.toUpperCase() + part.slice(1))
+            .join("");
+        if (!(discordName in PermissionFlagsBits)) {
+            throw new Error(`Unknown Discord permission: ${permission}`);
+        }
+    }
+    return [...new Set(permissions)];
+}
+function splitValues(value) {
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=permissions-module.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@helyx/bot",
+  "version": "0.1.0",
+  "description": "Production Discord runtime for the modular Helyx platform.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "bot",
+    "modular"
+  ],
+  "private": false,
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://helyx.gg/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "apps/bot"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "node --env-file-if-exists=../../.env --import tsx src/index.ts",
+    "start": "node --env-file-if-exists=../../.env dist/index.js"
+  },
+  "dependencies": {
+    "@helyx/config": "0.1.0",
+    "@helyx/core": "0.1.0",
+    "@helyx/database": "0.1.0",
+    "@helyx/framework": "0.1.0",
+    "@helyx/module-manifest": "0.1.0",
+    "@helyx/platform": "0.1.0",
+    "@helyx/sdk": "0.2.0",
+    "discord.js": "14.27.0",
+    "fastify": "5.10.0",
+    "pino": "10.3.1",
+    "zod": "4.4.3"
+  }
+}