@helyx/bot 0.1.0

package/dist/module-configuration.d.ts

@@ -0,0 +1,10 @@
+type CatalogueLocation = string | URL;
+type CatalogueReader = (path: CatalogueLocation) => Promise<string>;
+/**
+ * Combines the reviewed catalogue shipped by a hosted deployment with the
+ * optional runtime allowlist. A package being installed is never sufficient
+ * to make it executable: it must be named by one of these explicit sources.
+ */
+export declare function resolveModulePackageSpecifiers(configuredPackages: readonly string[], bundledCatalogueUrl?: URL, reader?: CatalogueReader, selectedCataloguePath?: string): Promise<string[]>;
+export {};
+//# sourceMappingURL=module-configuration.d.ts.map

package/dist/module-configuration.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+const officialModulePackage = /^@helyx\/module-[a-z0-9][a-z0-9-]*$/u;
+const modulePackageCatalogueSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    packages: z
+        .array(z.string().regex(officialModulePackage))
+        .superRefine((packages, context) => {
+        if (new Set(packages).size !== packages.length) {
+            context.addIssue({
+                code: "custom",
+                message: "package names must be unique",
+            });
+        }
+    }),
+})
+    .strict();
+const defaultCatalogueUrl = new URL("../hosted-modules.json", import.meta.url);
+/**
+ * Combines the reviewed catalogue shipped by a hosted deployment with the
+ * optional runtime allowlist. A package being installed is never sufficient
+ * to make it executable: it must be named by one of these explicit sources.
+ */
+export async function resolveModulePackageSpecifiers(configuredPackages, bundledCatalogueUrl = defaultCatalogueUrl, reader = (path) => readFile(path, "utf8"), selectedCataloguePath) {
+    const bundledPackages = await readModuleCatalogue(bundledCatalogueUrl, reader, true, "hosted");
+    const selectedPackages = selectedCataloguePath
+        ? await readModuleCatalogue(resolve(selectedCataloguePath), reader, false, "selected")
+        : [];
+    return [
+        ...new Set([
+            ...bundledPackages,
+            ...selectedPackages,
+            ...configuredPackages,
+        ]),
+    ];
+}
+async function readModuleCatalogue(location, reader, missingAllowed, label) {
+    try {
+        const source = await reader(location);
+        const parsed = modulePackageCatalogueSchema.safeParse(JSON.parse(source));
+        if (!parsed.success)
+            throw new Error("schema validation failed");
+        return parsed.data.packages;
+    }
+    catch (error) {
+        if (missingAllowed && isMissingFileError(error))
+            return [];
+        throw new Error(`Invalid ${label} module catalogue`, { cause: error });
+    }
+}
+function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+//# sourceMappingURL=module-configuration.js.map

package/dist/module-logging.d.ts

@@ -0,0 +1,21 @@
+import { type DatabasePool } from "@helyx/database";
+import type { ModuleDefinition, ModuleLogDetail, ModuleLoggingService } from "@helyx/sdk";
+import type { Client } from "discord.js";
+import { type InteractionLogger } from "./interactions.js";
+export declare class DiscordModuleLoggingService implements ModuleLoggingService {
+    #private;
+    private readonly client;
+    private readonly database;
+    private readonly logger;
+    constructor(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger);
+    emit(input: {
+        guildId: string;
+        moduleId: string;
+        eventId: string;
+        summary: string;
+        details?: readonly ModuleLogDetail[];
+    }): Promise<{
+        delivered: boolean;
+    }>;
+}
+//# sourceMappingURL=module-logging.d.ts.map

package/dist/module-logging.js

@@ -0,0 +1,97 @@
+import { InstallationRepository, ModuleConfigurationRepository, ModuleLoggingPolicyRepository, } from "@helyx/database";
+import { toReplyOptions } from "./interactions.js";
+const LOGGING_MODULE_ID = "helyx.logging";
+const VIOLET = 0x7c3aed;
+export class DiscordModuleLoggingService {
+    client;
+    database;
+    logger;
+    #modules;
+    #loggingInstalled;
+    constructor(client, database, modules, logger) {
+        this.client = client;
+        this.database = database;
+        this.logger = logger;
+        this.#modules = new Map(modules.map((module) => [module.manifest.id, module]));
+        this.#loggingInstalled = this.#modules.has(LOGGING_MODULE_ID);
+    }
+    async emit(input) {
+        try {
+            if (!this.#loggingInstalled)
+                return { delivered: false };
+            const source = this.#modules.get(input.moduleId);
+            const event = source?.logging?.events.find(({ id }) => id === input.eventId);
+            if (!source || !event) {
+                throw new Error("Module emitted an undeclared logging event");
+            }
+            const installations = new InstallationRepository(this.database);
+            if (!(await installations.isModuleEnabled(input.guildId, LOGGING_MODULE_ID))) {
+                return { delivered: false };
+            }
+            const [configuration, policy] = await Promise.all([
+                new ModuleConfigurationRepository(this.database).get(input.guildId, LOGGING_MODULE_ID),
+                new ModuleLoggingPolicyRepository(this.database).get(input.guildId, input.moduleId, input.eventId),
+            ]);
+            if (!(policy?.enabled ?? event.defaultEnabled)) {
+                return { delivered: false };
+            }
+            const channelId = configuration?.configuration.channelId;
+            if (typeof channelId !== "string" || !/^\d{17,20}$/u.test(channelId)) {
+                return { delivered: false };
+            }
+            const summary = normalizeText(input.summary, 500, "summary");
+            const details = (input.details ?? []).map(({ label, value }) => ({
+                label: normalizeText(label, 80, "detail label"),
+                value: normalizeText(value, 500, "detail value"),
+            }));
+            if (details.length > 10) {
+                throw new Error("Module logging details exceed the supported limit");
+            }
+            const guild = await this.client.guilds.fetch(input.guildId);
+            const channel = await guild.channels.fetch(channelId);
+            if (!channel?.isSendable()) {
+                throw new Error("Configured logging channel is not sendable");
+            }
+            const response = toReplyOptions({
+                allowedUserMentionIds: [],
+                componentsV2: {
+                    accentColor: VIOLET,
+                    text: [
+                        { content: "## Activity log" },
+                        { content: event.name, markdown: false },
+                        { content: summary, markdown: false },
+                        ...details.map(({ label, value }) => ({
+                            content: `${label}: ${value}`,
+                            markdown: false,
+                        })),
+                        { content: `Module: ${source.manifest.name}`, markdown: false },
+                    ],
+                },
+            });
+            await channel.send(response);
+            return { delivered: true };
+        }
+        catch (error) {
+            this.logger.warn({
+                event: "module_logging.delivery_failed",
+                moduleId: input.moduleId,
+                logEventId: input.eventId,
+                guildId: input.guildId,
+                error: safeError(error),
+            }, "Module activity log delivery failed");
+            return { delivered: false };
+        }
+    }
+}
+function normalizeText(value, maximum, label) {
+    const normalized = value.normalize("NFKC").trim();
+    if (normalized.length === 0 || normalized.length > maximum) {
+        throw new Error(`Module logging ${label} is invalid`);
+    }
+    return normalized;
+}
+function safeError(error) {
+    const value = error instanceof Error ? error : new Error(String(error));
+    return { name: value.name, message: value.message };
+}
+//# sourceMappingURL=module-logging.js.map

package/dist/modules.d.ts

@@ -0,0 +1,16 @@
+import type { ModuleDefinition } from "@helyx/sdk";
+type ModuleImporter = (specifier: string) => Promise<unknown>;
+type PackageJsonResolver = (specifier: string) => string;
+type PackageJsonReader = (path: string) => Promise<string>;
+interface LoadedDefinition {
+    specifier: string;
+    definition: ModuleDefinition;
+}
+export interface ConfiguredModulePackage extends LoadedDefinition {
+    packageRoot: string;
+}
+export declare function loadConfiguredModules(specifiers: readonly string[], importer?: ModuleImporter): Promise<ModuleDefinition[]>;
+export declare function loadConfiguredModulePackages(specifiers: readonly string[], importer?: ModuleImporter, resolvePackageJson?: PackageJsonResolver, readPackageJson?: PackageJsonReader): Promise<ConfiguredModulePackage[]>;
+export declare function validateContributionParity(definition: ModuleDefinition): void;
+export {};
+//# sourceMappingURL=modules.d.ts.map

package/dist/modules.js

@@ -0,0 +1,81 @@
+import { orderModuleManifests, parseModuleManifest, } from "@helyx/module-manifest";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+const officialModulePackage = /^@helyx\/module-[a-z0-9][a-z0-9-]*$/u;
+function isModuleDefinition(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.start === "function" &&
+        typeof candidate.stop === "function" &&
+        candidate.manifest !== undefined);
+}
+export async function loadConfiguredModules(specifiers, importer = (specifier) => import(specifier)) {
+    return (await loadDefinitions(specifiers, importer)).map(({ definition }) => definition);
+}
+export async function loadConfiguredModulePackages(specifiers, importer = (specifier) => import(specifier), resolvePackageJson = (specifier) => createRequire(import.meta.url).resolve(`${specifier}/package.json`), readPackageJson = (path) => readFile(path, "utf8")) {
+    const loaded = await loadDefinitions(specifiers, importer);
+    return Promise.all(loaded.map(async ({ specifier, definition }) => {
+        const packageJsonPath = resolvePackageJson(specifier);
+        const packageJson = JSON.parse(await readPackageJson(packageJsonPath));
+        if (typeof packageJson !== "object" ||
+            packageJson === null ||
+            packageJson.name !== specifier ||
+            packageJson.version !==
+                definition.manifest.version) {
+            throw new Error(`Module package metadata mismatch: ${specifier}`);
+        }
+        return {
+            specifier,
+            definition,
+            packageRoot: dirname(packageJsonPath),
+        };
+    }));
+}
+async function loadDefinitions(specifiers, importer) {
+    const loaded = [];
+    for (const specifier of specifiers) {
+        if (!officialModulePackage.test(specifier)) {
+            throw new Error(`Untrusted or invalid module package specifier: ${specifier}`);
+        }
+        const namespace = await importer(specifier);
+        const definition = typeof namespace === "object" && namespace !== null
+            ? namespace.default
+            : undefined;
+        if (!isModuleDefinition(definition)) {
+            throw new Error(`Module package has no valid default export: ${specifier}`);
+        }
+        definition.manifest = parseModuleManifest(definition.manifest);
+        validateContributionParity(definition);
+        loaded.push({ specifier, definition });
+    }
+    const orderedManifests = orderModuleManifests(loaded.map(({ definition }) => definition.manifest));
+    const byId = new Map(loaded.map((item) => [item.definition.manifest.id, item]));
+    return orderedManifests.map((manifest) => byId.get(manifest.id));
+}
+export function validateContributionParity(definition) {
+    const executableCommands = (definition.interactions?.commands ?? []).map(({ name }) => name);
+    const executableEvents = [
+        ...(definition.events?.messageReactionAdd ?? []),
+        ...(definition.events?.guildMemberAdd ?? []),
+    ].map(({ type }) => type);
+    const executableLogs = (definition.logging?.events ?? []).map(({ id }) => id);
+    const executableDashboardActions = (definition.dashboardActions ?? []).map(({ id }) => id);
+    assertSameContributionIds(definition.manifest.contributions.commands, executableCommands, "commands");
+    assertSameContributionIds(definition.manifest.contributions.events, executableEvents, "events");
+    assertSameContributionIds(definition.manifest.contributions.logs ?? [], executableLogs, "logs");
+    assertSameContributionIds(definition.manifest.dashboard?.actions?.map(({ id }) => id) ?? [], executableDashboardActions, "dashboard actions");
+}
+function assertSameContributionIds(declared, executable, label) {
+    if (new Set(executable).size !== executable.length) {
+        throw new Error(`Module has duplicate executable ${label}`);
+    }
+    const declaredSorted = [...declared].sort();
+    const executableSorted = [...executable].sort();
+    if (declaredSorted.length !== executableSorted.length ||
+        declaredSorted.some((value, index) => value !== executableSorted[index])) {
+        throw new Error(`Module manifest ${label} do not match executable contributions`);
+    }
+}
+//# sourceMappingURL=modules.js.map

package/dist/permissions-module.d.ts

@@ -0,0 +1,3 @@
+import { type ModuleDefinition } from "@helyx/sdk";
+export declare function createPermissionsModule(configurableModules: readonly ModuleDefinition[]): ModuleDefinition;
+//# sourceMappingURL=permissions-module.d.ts.map