@helyx/bot 0.4.33 → 0.4.36

package/dist/module-availability-control.js

@@ -0,0 +1,61 @@
+import { isCustomerSelectableModule } from "@helyx/module-manifest";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createHash } from "node:crypto";
+export function availabilityCatalogueDefinitions(modules) {
+    return modules
+        .filter((module) => isCustomerSelectableModule(module.manifest))
+        .map(({ manifest }) => ({
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        releaseStatus: manifest.releaseStatus,
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name, "en-GB"));
+}
+export function availabilityCatalogueSnapshot(definitions) {
+    const modules = definitions.map((module) => ({ ...module }));
+    return {
+        catalogueDigest: createHash("sha256")
+            .update(JSON.stringify(modules))
+            .digest("hex"),
+        modules,
+    };
+}
+export function availabilityCatalogue(definitions) {
+    return Promise.resolve(availabilityCatalogueSnapshot(definitions));
+}
+export function moduleAvailabilityService(services) {
+    if (!services.has(HELYX_SERVICE_NAMES.moduleAvailability))
+        return undefined;
+    const service = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
+    return typeof service?.get === "function" &&
+        typeof service.isAvailable === "function"
+        ? service
+        : undefined;
+}
+export function moduleAvailabilityStates(services, moduleIds) {
+    const availability = moduleAvailabilityService(services);
+    return Promise.all(moduleIds.map((moduleId) => availability
+        ? availability.get(moduleId)
+        : Promise.resolve({
+            moduleId,
+            globallyDisabled: false,
+            revision: 0n,
+            generation: 0n,
+            updatedAt: null,
+        })));
+}
+export function dashboardModuleStatus(globallyDisabled, moduleId, installation) {
+    if (globallyDisabled.has(moduleId))
+        return "unavailable";
+    if (!installation)
+        return "unavailable";
+    return installation.enabled ? "enabled" : "disabled";
+}
+export function disabledModuleSummary(states) {
+    const ids = states
+        .filter(({ globallyDisabled }) => globallyDisabled)
+        .map(({ moduleId }) => moduleId);
+    return { ids, set: new Set(ids) };
+}
+//# sourceMappingURL=module-availability-control.js.map

package/dist/modules.js

@@ -1,4 +1,5 @@
 import { orderModuleManifests, parseModuleManifest, } from "@helyx/module-manifest";
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID } from "@helyx/sdk";
 import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -102,6 +103,28 @@ export function validateContributionParity(definition) {
         throw new Error("Module requests an unsupported or duplicate Discord capability");
     }
     const executableCommands = (definition.interactions?.commands ?? []).map(({ name }) => name);
+    const nexusCommandPaths = new Set();
+    for (const command of definition.nexusCommands ?? []) {
+        const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === command.path);
+        if (!spec || spec.ownerModuleId !== definition.manifest.id) {
+            throw new Error(`Module ${definition.manifest.id} cannot contribute Nexus command ${command.path}`);
+        }
+        if (nexusCommandPaths.has(command.path)) {
+            throw new Error(`Duplicate Nexus command path for ${definition.manifest.id}: ${command.path}`);
+        }
+        nexusCommandPaths.add(command.path);
+    }
+    if (definition.manifest.id !== NEXUS_ROOT_MODULE_ID) {
+        executableCommands.push(...[...nexusCommandPaths].map((path) => `nexus.${path}`));
+        if (nexusCommandPaths.size > 0 &&
+            !definition.manifest.dependencies.some(({ id }) => id === NEXUS_ROOT_MODULE_ID)) {
+            throw new Error(`Module ${definition.manifest.id} contributes Nexus commands without depending on Nexus Core`);
+        }
+    }
+    if (definition.manifest.id !== NEXUS_ROOT_MODULE_ID &&
+        definition.interactions?.commands?.some(({ name }) => name === "nexus")) {
+        throw new Error("Nexus Core must be the sole owner of /nexus");
+    }
     const executableEvents = [
         ...(definition.events?.privilegedMessageCreate ?? []),
         ...(definition.events?.guildMessageCreate ?? []),
@@ -135,7 +158,7 @@ export function validateContributionParity(definition) {
 function validatePrivacyParity(definition) {
     if (definition.manifest.manifestVersion === "0.1") {
         if (definition.privacy !== undefined) {
-            throw new Error("Module executable privacy provider requires manifest version 0.2");
+            throw new Error("Module executable privacy provider requires manifest version 0.2 or later");
         }
         return;
     }

package/dist/nexus-commands.d.ts

@@ -0,0 +1,13 @@
+import { type CommandContribution, type ModuleDefinition } from "@helyx/sdk";
+export interface CommandRouteOwner {
+    moduleId: string;
+    moduleName: string;
+}
+export interface RegisteredCommand {
+    moduleId: string;
+    moduleName: string;
+    contribution: CommandContribution;
+    routeOwners?: ReadonlyMap<string, CommandRouteOwner>;
+}
+export declare function collectCommandRegistrations(modules: readonly ModuleDefinition[]): Map<string, RegisteredCommand>;
+//# sourceMappingURL=nexus-commands.d.ts.map

package/dist/nexus-commands.js

@@ -0,0 +1,100 @@
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID, } from "@helyx/sdk";
+export function collectCommandRegistrations(modules) {
+    const registrations = modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        moduleName: module.manifest.name,
+        contribution,
+    })));
+    const nexusContributions = modules.flatMap((module) => (module.nexusCommands ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        moduleName: module.manifest.name,
+        contribution,
+    })));
+    if (nexusContributions.length > 0) {
+        const roots = registrations.filter(({ contribution }) => contribution.name === "nexus");
+        if (roots.length !== 1 || roots[0].moduleId !== NEXUS_ROOT_MODULE_ID) {
+            throw new Error("Nexus Core must be the sole owner of /nexus");
+        }
+        const root = roots[0];
+        if (root.contribution.execute ||
+            root.contribution.options?.length ||
+            root.contribution.subcommands?.length ||
+            root.contribution.subcommandGroups?.length) {
+            throw new Error("Nexus Core /nexus must be composed from Nexus commands");
+        }
+        const composed = composeNexusCommand(root, nexusContributions);
+        registrations.splice(registrations.indexOf(root), 1, composed);
+    }
+    return uniqueRegistrations(registrations);
+}
+function composeNexusCommand(root, contributions) {
+    const byPath = new Map(contributions.map((item) => {
+        const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === item.contribution.path);
+        if (!spec || spec.ownerModuleId !== item.moduleId) {
+            throw new Error(`Module ${item.moduleId} cannot contribute Nexus command ${item.contribution.path}`);
+        }
+        return [item.contribution.path, item];
+    }));
+    if (byPath.size !== contributions.length) {
+        throw new Error("Duplicate Nexus command path");
+    }
+    const subcommands = [];
+    const groups = new Map();
+    const routeOwners = new Map();
+    for (const spec of NEXUS_COMMAND_SPECS) {
+        const item = byPath.get(spec.path);
+        if (!item)
+            continue;
+        routeOwners.set(spec.path, {
+            moduleId: item.moduleId,
+            moduleName: item.moduleName,
+        });
+        const [first, second] = spec.path.split(".");
+        const command = toSubcommand(item.contribution, second ?? first);
+        if (!second) {
+            subcommands.push(command);
+            continue;
+        }
+        const current = groups.get(first);
+        const group = current ?? {
+            name: first,
+            description: "groupDescription" in spec
+                ? spec.groupDescription
+                : `Manage Nexus ${first}`,
+            subcommands: [],
+        };
+        groups.set(first, {
+            ...group,
+            subcommands: [...group.subcommands, command],
+        });
+    }
+    return {
+        ...root,
+        contribution: {
+            ...root.contribution,
+            subcommands,
+            subcommandGroups: [...groups.values()],
+        },
+        routeOwners,
+    };
+}
+function toSubcommand(contribution, name) {
+    const subcommand = {
+        ...contribution,
+        name,
+        permissionId: `nexus.${contribution.path}`,
+    };
+    delete subcommand.path;
+    return subcommand;
+}
+function uniqueRegistrations(items) {
+    const result = new Map();
+    for (const item of items) {
+        const key = item.contribution.name;
+        if (result.has(key))
+            throw new Error(`Duplicate command name: ${key}`);
+        result.set(key, item);
+    }
+    return result;
+}
+//# sourceMappingURL=nexus-commands.js.map

package/dist/numeric-barriers.d.ts

@@ -0,0 +1,11 @@
+import type { NumericWriteBehindScope, NumericWriteBehindService } from "@helyx/sdk";
+type GuildScope = NumericWriteBehindScope & {
+    guildId: string;
+};
+export declare function runNestedGuildBarriers(input: {
+    scopes: readonly GuildScope[];
+    writeBehind: NumericWriteBehindService;
+    operation(): Promise<unknown>;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=numeric-barriers.d.ts.map

package/dist/numeric-barriers.js

@@ -0,0 +1,14 @@
+export async function runNestedGuildBarriers(input) {
+    const run = async (index, inheritedSignal) => {
+        inheritedSignal?.throwIfAborted();
+        const scope = input.scopes[index];
+        if (!scope) {
+            await input.operation();
+            inheritedSignal?.throwIfAborted();
+            return;
+        }
+        await input.writeBehind.runGuildBarrier(scope, (signal) => run(index + 1, inheritedSignal ? AbortSignal.any([inheritedSignal, signal]) : signal));
+    };
+    await run(0);
+}
+//# sourceMappingURL=numeric-barriers.js.map

package/dist/numeric-write-behind-proxy.d.ts

@@ -19,13 +19,13 @@ export declare class WorkerNumericWriteBehindProxy implements NumericWriteBehind
         subjectId: string;
     }): Promise<void>;
     flushModule(input: NumericWriteBehindScope): Promise<void>;
-    runMemberBarrier<Result>(input: NumericWriteBehindMemberScope, operation: () => Promise<Result>): Promise<Result>;
+    runMemberBarrier<Result>(input: NumericWriteBehindMemberScope, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     runGuildBarrier<Result>(input: NumericWriteBehindScope & {
         guildId: string;
-    }, operation: () => Promise<Result>): Promise<Result>;
+    }, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     runSubjectBarrier<Result>(input: NumericWriteBehindScope & {
         subjectId: string;
-    }, operation: () => Promise<Result>): Promise<Result>;
+    }, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     suppressSubject(input: NumericWriteBehindScope & {
         subjectId: string;
         cutoff: Date;
@@ -55,7 +55,7 @@ export declare class WorkerNumericWriteBehindProxy implements NumericWriteBehind
     clearSubjectCooldown(input: NumericWriteBehindScope & {
         subjectId: string;
     }): Promise<void>;
-    subscribeCommitted(input: NumericWriteBehindScope, handler: (batch: NumericWriteBehindCommittedBatch) => void | Promise<void>): () => void;
+    subscribeCommitted(input: NumericWriteBehindScope, handler: (batch: NumericWriteBehindCommittedBatch, signal: AbortSignal) => void | Promise<void>): () => void;
     stop(): void;
 }
 export declare function encodeNumericIpcValue(input: unknown): unknown;

package/dist/numeric-write-behind-proxy.js

@@ -1,6 +1,7 @@
 import {} from "@helyx/sdk";
 import { randomUUID } from "node:crypto";
 import { assertShardMessageSize, SHARD_CONTROL_TIMEOUT_MS, shardNumericCommittedSchema, shardNumericResponseSchema, } from "./shard-contracts.js";
+import { RenewableLease } from "./renewable-lease.js";
 export class WorkerNumericWriteBehindProxy {
     #identity;
     #pending = new Map();
@@ -157,37 +158,44 @@ export class WorkerNumericWriteBehindProxy {
             ...(input.guildId ? { guildId: input.guildId } : {}),
             ...(input.subjectId ? { subjectId: input.subjectId } : {}),
         }));
-        let renewalFailure;
-        const renew = setInterval(() => {
-            void this.#call({
+        const renewal = new RenewableLease({
+            intervalMs: 20_000,
+            renew: () => this.#call({
                 kind: "barrier.renew",
                 ...scope(input),
                 barrierType,
                 ...(input.guildId ? { guildId: input.guildId } : {}),
                 ...(input.subjectId ? { subjectId: input.subjectId } : {}),
                 barrierId: acquired.barrierId,
-            }).catch((error) => {
-                renewalFailure =
-                    error instanceof Error
-                        ? error
-                        : new Error("Numeric barrier renewal failed");
+            }).then(() => undefined),
+        });
+        renewal.start();
+        const failures = [];
+        let result;
+        let completed = false;
+        try {
+            result = await renewal.run(async (signal) => {
+                if (barrierType === "member")
+                    await this.flushMember(input);
+                else if (barrierType === "guild")
+                    await this.flushGuild(input);
+                else
+                    await this.flushSubject(input);
+                signal.throwIfAborted();
+                return operation(signal);
             });
-        }, 20_000);
-        renew.unref();
+            completed = true;
+        }
+        catch (error) {
+            failures.push(error);
+        }
         try {
-            if (barrierType === "member")
-                await this.flushMember(input);
-            else if (barrierType === "guild")
-                await this.flushGuild(input);
-            else
-                await this.flushSubject(input);
-            const result = await operation();
-            if (renewalFailure)
-                throw renewalFailure;
-            return result;
+            await renewal.stop();
         }
-        finally {
-            clearInterval(renew);
+        catch (error) {
+            failures.push(error);
+        }
+        try {
             await this.#call({
                 kind: "barrier.release",
                 ...scope(input),
@@ -197,6 +205,16 @@ export class WorkerNumericWriteBehindProxy {
                 barrierId: acquired.barrierId,
             });
         }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, "Numeric barrier cleanup failed");
+        if (!completed)
+            throw new Error("Numeric barrier operation did not complete");
+        return result;
     }
     async #handleCommitted(committed) {
         let response;
@@ -204,8 +222,11 @@ export class WorkerNumericWriteBehindProxy {
             if (new Date(committed.deadlineAt).getTime() <= Date.now())
                 throw new Error("Numeric committed notification expired");
             const batch = decodeIpcValue(committed.payload);
-            for (const subscriber of this.#subscribers.get(scopeKey(committed.scope)) ?? [])
-                await subscriber(batch);
+            const signal = AbortSignal.timeout(Math.max(1, new Date(committed.deadlineAt).getTime() - Date.now()));
+            for (const subscriber of this.#subscribers.get(scopeKey(committed.scope)) ?? []) {
+                signal.throwIfAborted();
+                await subscriber(batch, signal);
+            }
             response = {
                 version: 1,
                 type: "helyx.numeric.committed.response",

package/dist/numeric-write-behind-redis.d.ts

@@ -51,13 +51,13 @@ export declare class RedisNumericWriteBehindService implements NumericWriteBehin
         subjectId: string;
     }): Promise<void>;
     flushModule(input: NumericWriteBehindScope): Promise<void>;
-    runMemberBarrier<Result>(input: NumericWriteBehindMemberScope, operation: () => Promise<Result>): Promise<Result>;
+    runMemberBarrier<Result>(input: NumericWriteBehindMemberScope, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     runGuildBarrier<Result>(input: NumericWriteBehindScope & {
         guildId: string;
-    }, operation: () => Promise<Result>): Promise<Result>;
+    }, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     runSubjectBarrier<Result>(input: NumericWriteBehindScope & {
         subjectId: string;
-    }, operation: () => Promise<Result>): Promise<Result>;
+    }, operation: (signal: AbortSignal) => Promise<Result>): Promise<Result>;
     suppressSubject(input: NumericWriteBehindScope & {
         subjectId: string;
         cutoff: Date;
@@ -87,7 +87,7 @@ export declare class RedisNumericWriteBehindService implements NumericWriteBehin
     clearSubjectCooldown(input: NumericWriteBehindScope & {
         subjectId: string;
     }): Promise<void>;
-    subscribeCommitted(input: NumericWriteBehindScope, handler: (batch: NumericWriteBehindCommittedBatch) => void | Promise<void>): () => void;
+    subscribeCommitted(input: NumericWriteBehindScope, handler: (batch: NumericWriteBehindCommittedBatch, signal: AbortSignal) => void | Promise<void>): () => void;
     health(): NumericWriteBehindHealth;
     acquireBarrier(input: {
         scope: NumericWriteBehindScope;