@helyx/bot 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# Helyx bot
+
+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.
+
+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.
+
+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.
+
+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.
+
+When `HELYX_BOT_CONTROL_SECRET` is configured, the bot also starts a private authenticated HTTP control server on `HELYX_BOT_CONTROL_PORT`. The dashboard API uses this service to obtain real Discord roles and channels and to apply validated module, configuration and permission changes. Only `/health` is unauthenticated; all `/v1` routes require the shared bearer secret. Keep this endpoint on a private service network and do not assign it a public domain.
+
+For packaged operation use `helyx start`. `helyx migrate` applies core database migrations without Discord, and read-only `helyx doctor` verifies environment, PostgreSQL migration history, and configured package metadata.

package/dist/control-server.d.ts

@@ -0,0 +1,198 @@
+import { type DatabasePool } from "@helyx/database";
+import { type DashboardActionResult, type MessageResponse, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import { type Client } from "discord.js";
+import { type FastifyInstance } from "fastify";
+interface DashboardPermissionPolicy {
+    preset: "everyone" | "moderators" | "administrators" | "custom";
+    allowedRoleIds: string[];
+    deniedRoleIds: string[];
+}
+interface DashboardCommandDefinition {
+    id: string;
+    name: string;
+    description: string;
+    defaultPreset: DashboardPermissionPolicy["preset"];
+}
+interface DashboardLogEventDefinition {
+    id: string;
+    name: string;
+    description: string;
+    defaultEnabled: boolean;
+}
+interface DashboardActionDefinition {
+    id: string;
+    label: string;
+    description: string;
+    buttonLabel: string;
+    style: "primary" | "secondary" | "danger";
+}
+interface DashboardModuleDefinition {
+    id: string;
+    name: string;
+    version: string;
+    summary: string;
+    category: string;
+    icon: string;
+    availability: "available";
+    requiredPermissions: string[];
+    settings: readonly unknown[];
+    commands: DashboardCommandDefinition[];
+    logEvents: DashboardLogEventDefinition[];
+    actions: DashboardActionDefinition[];
+}
+interface DashboardLoggingPolicy {
+    eventId: string;
+    enabled: boolean;
+    version: number;
+}
+interface DashboardPermissionState {
+    version: number;
+    module: DashboardPermissionPolicy;
+    commands: Array<{
+        commandId: string;
+        version: number;
+        enabled: boolean;
+        policy: DashboardPermissionPolicy;
+    }>;
+}
+export interface BotControlGuildResources {
+    channels: Array<{
+        id: string;
+        name: string;
+        type: "guild_text" | "guild_announcement";
+    }>;
+    roles: Array<{
+        id: string;
+        name: string;
+        colour: string;
+    }>;
+}
+export interface BotControlGuildResourceDirectory {
+    getGuildResources(guildId: string): Promise<BotControlGuildResources>;
+    sendToChannel(channelId: string, response: MessageResponse): Promise<{
+        messageId: string;
+    }>;
+    deleteChannelMessage(channelId: string, messageId: string): Promise<void>;
+}
+export declare class DiscordGuildResourceDirectory implements BotControlGuildResourceDirectory {
+    private readonly client;
+    constructor(client: Client);
+    getGuildResources(guildId: string): Promise<BotControlGuildResources>;
+    sendToChannel(channelId: string, response: MessageResponse): Promise<{
+        messageId: string;
+    }>;
+    deleteChannelMessage(channelId: string, messageId: string): Promise<void>;
+}
+export interface BotControlState {
+    channels: BotControlGuildResources["channels"];
+    roles: BotControlGuildResources["roles"];
+    modules: DashboardModuleDefinition[];
+    moduleStatuses: Record<string, "enabled" | "disabled" | "unavailable">;
+    configurations: Record<string, {
+        version: number;
+        value: Record<string, unknown>;
+    } | undefined>;
+    permissions: Record<string, DashboardPermissionState>;
+    logging: Record<string, DashboardLoggingPolicy[]>;
+}
+export interface BotControlHandler {
+    getGuildState(guildId: string): Promise<BotControlState>;
+    setModuleStatus(input: {
+        guildId: string;
+        moduleId: string;
+        enabled: boolean;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<BotControlState>;
+    updateConfiguration(input: {
+        guildId: string;
+        moduleId: string;
+        value: Record<string, unknown>;
+        expectedVersion: number | null;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<{
+        value: Record<string, unknown>;
+        version: number;
+    }>;
+    updatePermissions(input: {
+        guildId: string;
+        moduleId: string;
+        state: DashboardPermissionState;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardPermissionState>;
+    updateLoggingPolicy(input: {
+        guildId: string;
+        moduleId: string;
+        eventId: string;
+        enabled: boolean;
+        expectedVersion: number;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardLoggingPolicy>;
+    executeDashboardAction(input: {
+        guildId: string;
+        moduleId: string;
+        actionId: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardActionResult>;
+}
+export declare class BotControlService implements BotControlHandler {
+    #private;
+    private readonly database;
+    private readonly resources;
+    constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess);
+    getGuildState(guildId: string): Promise<BotControlState>;
+    setModuleStatus(input: {
+        guildId: string;
+        moduleId: string;
+        enabled: boolean;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<BotControlState>;
+    updateConfiguration(input: {
+        guildId: string;
+        moduleId: string;
+        value: Record<string, unknown>;
+        expectedVersion: number | null;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<{
+        value: Record<string, unknown>;
+        version: number;
+    }>;
+    updatePermissions(input: {
+        guildId: string;
+        moduleId: string;
+        state: DashboardPermissionState;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardPermissionState>;
+    updateLoggingPolicy(input: {
+        guildId: string;
+        moduleId: string;
+        eventId: string;
+        enabled: boolean;
+        expectedVersion: number;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardLoggingPolicy>;
+    executeDashboardAction(input: {
+        guildId: string;
+        moduleId: string;
+        actionId: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<DashboardActionResult>;
+}
+export declare function createBotControlServer(input: {
+    service: BotControlHandler;
+    secret: string;
+    logger?: boolean | {
+        level: string;
+    };
+}): Promise<FastifyInstance>;
+export {};
+//# sourceMappingURL=control-server.d.ts.map