@helyx/bot 0.4.37 → 0.4.38

package/dist/guild-command-read-service.d.ts

@@ -0,0 +1,201 @@
+import { type GuildCommandBudgetClass, type GuildCommandHealth, type GuildCommandHistoryRecord, type GuildCommandRequestRecord, type GuildCommandRequestSource, type GuildCommandStateRecord, type GuildCommandVisibilityProfile } from "@helyx/database";
+import type { ModuleDefinition } from "@helyx/sdk";
+import type { Pool } from "pg";
+import type { GuildCommandWorkerHealth } from "./guild-command-worker.js";
+export interface GuildCommandReadStatus {
+    mode: "dry_run" | "live";
+    discordWritesEnabled: boolean;
+    state: ReturnType<typeof serializeState> | null;
+    activeRequest: ReturnType<typeof serializeRequest> | null;
+    capacity: {
+        customerUsed: number;
+        customerLimit: number;
+        ownerSystemUsed: number;
+        ownerSystemLimit: number;
+        windowStartedAt: string;
+    };
+}
+export interface GuildCommandReadHandler {
+    getStatus(guildId: string): Promise<GuildCommandReadStatus>;
+    requestReconciliation(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        source: Extract<GuildCommandRequestSource, "customer_rebuild" | "owner_repair">;
+        budgetClass: Extract<GuildCommandBudgetClass, "customer" | "owner">;
+        delayMs: number;
+        summary: string;
+    }): Promise<GuildCommandReadStatus>;
+    refreshStatus(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<GuildCommandReadStatus>;
+    changeProfile(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        profile: GuildCommandVisibilityProfile;
+        reasonSummary: string;
+    }): Promise<GuildCommandReadStatus>;
+    setMigrationHold(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        enabled: boolean;
+    }): Promise<GuildCommandReadStatus>;
+    listHistory(input: {
+        guildId: string;
+        beforeEventId?: bigint;
+        since?: Date;
+        limit?: number;
+    }): Promise<{
+        items: Array<ReturnType<typeof serializeHistory>>;
+        nextCursor: string | null;
+    }>;
+    getHealth(): Promise<GuildCommandHealth & {
+        mode: "dry_run" | "live";
+        workerRunning: boolean;
+        activeCount: number;
+        discordWritesEnabled: boolean;
+    }>;
+    previewFirstTimeSetup(moduleIds: string[]): Promise<{
+        selectedModuleIds: string[];
+        rootCount: number;
+        subcommandCount: number;
+        commands: Array<{
+            name: string;
+            subcommands: string[];
+        }>;
+    }>;
+    reconcileModuleAvailability(input: {
+        moduleId: string;
+        correlationId: string;
+    }): Promise<{
+        scheduledGuildCount: number;
+    }>;
+}
+export declare class GuildCommandReadService implements GuildCommandReadHandler {
+    #private;
+    private readonly database;
+    private readonly applicationId;
+    private readonly workerHealth?;
+    private readonly discordToken?;
+    private readonly guildCommandWritesEnabled;
+    private readonly writeGuildIds;
+    private readonly writeAllGuilds;
+    private readonly modules;
+    constructor(database: Pool, applicationId: string, workerHealth?: (() => Promise<GuildCommandWorkerHealth> | undefined) | undefined, discordToken?: string | undefined, guildCommandWritesEnabled?: boolean, writeGuildIds?: readonly string[], writeAllGuilds?: boolean, modules?: readonly ModuleDefinition[]);
+    previewFirstTimeSetup(moduleIds: string[]): Promise<{
+        selectedModuleIds: string[];
+        rootCount: number;
+        subcommandCount: number;
+        commands: {
+            name: string;
+            subcommands: string[];
+        }[];
+    }>;
+    getStatus(guildId: string): Promise<GuildCommandReadStatus>;
+    requestReconciliation(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        source: "customer_rebuild" | "owner_repair";
+        budgetClass: "customer" | "owner";
+        delayMs: number;
+        summary: string;
+    }): Promise<GuildCommandReadStatus>;
+    reconcileModuleAvailability(input: {
+        moduleId: string;
+        correlationId: string;
+    }): Promise<{
+        scheduledGuildCount: number;
+    }>;
+    refreshStatus(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+    }): Promise<GuildCommandReadStatus>;
+    changeProfile(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        profile: GuildCommandVisibilityProfile;
+        reasonSummary: string;
+    }): Promise<GuildCommandReadStatus>;
+    setMigrationHold(input: {
+        guildId: string;
+        actorUserId: string;
+        correlationId: string;
+        expectedRevision: bigint;
+        enabled: boolean;
+    }): Promise<GuildCommandReadStatus>;
+    listHistory(input: {
+        guildId: string;
+        beforeEventId?: bigint;
+        since?: Date;
+        limit?: number;
+    }): Promise<{
+        items: Array<ReturnType<typeof serializeHistory>>;
+        nextCursor: string | null;
+    }>;
+    getHealth(): Promise<GuildCommandWorkerHealth>;
+}
+declare function serializeState(state: GuildCommandStateRecord): {
+    applicationId: string;
+    guildId: string;
+    visibilityProfile: GuildCommandVisibilityProfile;
+    desiredDefinitionHash: string | null;
+    desiredRootCount: number;
+    desiredSubcommandCount: number;
+    lastObservedDefinitionHash: string | null;
+    installedRootCount: number;
+    state: import("@helyx/database").GuildCommandState;
+    desiredRevision: string;
+    scheduledAt: string | null;
+    startedAt: string | null;
+    lastAttemptedAt: string | null;
+    lastSuccessfulAt: string | null;
+    lastSafeCode: string | null;
+    setupState: import("@helyx/database").GuildCommandSetupState;
+    updatedAt: string;
+};
+declare function serializeRequest(request: GuildCommandRequestRecord): {
+    requestId: string;
+    source: GuildCommandRequestSource;
+    requestedRevision: string;
+    notBefore: string;
+    budgetClass: GuildCommandBudgetClass;
+    status: import("@helyx/database").GuildCommandRequestStatus;
+    attemptCount: number;
+    attemptLimit: number;
+    correlationId: string;
+    lastSafeCode: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+declare function serializeHistory(history: GuildCommandHistoryRecord): {
+    eventId: string;
+    eventType: string;
+    summary: string;
+    actorUserId: string | null;
+    moduleId: string | null;
+    requestId: string | null;
+    correlationId: string;
+    createdCount: number;
+    updatedCount: number;
+    removedCount: number;
+    createdCommands: string[];
+    updatedCommands: string[];
+    removedCommands: string[];
+    creationsUsed: number;
+    resultState: import("@helyx/database").GuildCommandState | null;
+    createdAt: string;
+};
+export {};
+//# sourceMappingURL=guild-command-read-service.d.ts.map

package/dist/guild-command-read-service.js

@@ -0,0 +1,272 @@
+import { GuildCommandRepository, GuildCommandRevisionConflictError, InstallationRepository, } from "@helyx/database";
+import { isCustomerSelectableModule } from "@helyx/module-manifest";
+import { createHash } from "node:crypto";
+import { REST, Routes } from "discord.js";
+import { guildCommandDefinitionHash, projectGuildCommands, } from "./guild-command-projection.js";
+export class GuildCommandReadService {
+    database;
+    applicationId;
+    workerHealth;
+    discordToken;
+    guildCommandWritesEnabled;
+    writeGuildIds;
+    writeAllGuilds;
+    modules;
+    #repository;
+    constructor(database, applicationId, workerHealth, discordToken, guildCommandWritesEnabled = false, writeGuildIds = [], writeAllGuilds = false, modules = []) {
+        this.database = database;
+        this.applicationId = applicationId;
+        this.workerHealth = workerHealth;
+        this.discordToken = discordToken;
+        this.guildCommandWritesEnabled = guildCommandWritesEnabled;
+        this.writeGuildIds = writeGuildIds;
+        this.writeAllGuilds = writeAllGuilds;
+        this.modules = modules;
+        this.#repository = new GuildCommandRepository(this.database);
+    }
+    previewFirstTimeSetup(moduleIds) {
+        const requested = new Set(moduleIds);
+        const byId = new Map(this.modules.map((module) => [module.manifest.id, module]));
+        for (const moduleId of requested) {
+            const module = byId.get(moduleId);
+            if (!module ||
+                !isCustomerSelectableModule(module.manifest) ||
+                !["live", "beta"].includes(module.manifest.releaseStatus))
+                throw new Error("Command preview contains an unavailable module");
+        }
+        const projection = projectGuildCommands({
+            modules: this.modules,
+            enabledModuleIds: requested,
+            profile: "enabled_only",
+        });
+        return Promise.resolve({
+            selectedModuleIds: [...projection.selectedModuleIds],
+            rootCount: projection.rootCount,
+            subcommandCount: projection.subcommandCount,
+            commands: projection.definitions.map((command) => ({
+                name: `/${command.name}`,
+                subcommands: command.executablePaths.map((path) => path.replaceAll(".", " ")),
+            })),
+        });
+    }
+    async getStatus(guildId) {
+        // This is a display snapshot, not a mutation boundary. Command mutations
+        // retain their transactional revision, lease, fencing and ledger checks.
+        const [existingState, activeRequest, capacity] = await Promise.all([
+            this.#repository.getState(this.applicationId, guildId),
+            this.#repository.getActiveRequest(this.applicationId, guildId),
+            this.#repository.getCapacity(this.applicationId, guildId),
+        ]);
+        const state = existingState ??
+            (await this.#repository.ensureState({
+                applicationId: this.applicationId,
+                guildId,
+                setupState: "incomplete",
+            }));
+        return {
+            mode: this.guildCommandWritesEnabled &&
+                (this.writeAllGuilds || this.writeGuildIds.includes(guildId))
+                ? "live"
+                : "dry_run",
+            discordWritesEnabled: this.guildCommandWritesEnabled &&
+                (this.writeAllGuilds || this.writeGuildIds.includes(guildId)),
+            state: state ? serializeState(state) : null,
+            activeRequest: activeRequest ? serializeRequest(activeRequest) : null,
+            capacity: {
+                ...capacity,
+                windowStartedAt: capacity.windowStartedAt.toISOString(),
+            },
+        };
+    }
+    async requestReconciliation(input) {
+        const idempotencyHash = createHash("sha256")
+            .update(`${input.source}:${input.correlationId}`)
+            .digest("hex");
+        await this.#repository.schedule({
+            applicationId: this.applicationId,
+            guildId: input.guildId,
+            idempotencyKey: `${input.source}:${idempotencyHash}`,
+            source: input.source,
+            budgetClass: input.budgetClass,
+            correlationId: input.correlationId,
+            actorUserId: input.actorUserId,
+            summary: input.summary,
+            delayMs: input.delayMs,
+            expectedRevision: input.expectedRevision,
+        });
+        return this.getStatus(input.guildId);
+    }
+    async reconcileModuleAvailability(input) {
+        const installations = new InstallationRepository(this.database);
+        let cursor;
+        let scheduledGuildCount = 0;
+        do {
+            const page = await installations.listActiveGuildIdsWithEnabledModule({
+                moduleId: input.moduleId,
+                ...(cursor ? { cursor } : {}),
+                limit: 500,
+            });
+            for (let offset = 0; offset < page.guildIds.length; offset += 25) {
+                const guildIds = page.guildIds.slice(offset, offset + 25);
+                await Promise.all(guildIds.map((guildId) => this.#repository.schedule({
+                    applicationId: this.applicationId,
+                    guildId,
+                    idempotencyKey: `availability:${input.moduleId}:${input.correlationId}`,
+                    source: "release_migration",
+                    budgetClass: "system",
+                    correlationId: input.correlationId,
+                    moduleId: input.moduleId,
+                    summary: `Global availability changed for ${input.moduleId}.`,
+                    delayMs: 0,
+                })));
+                scheduledGuildCount += guildIds.length;
+            }
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+        return { scheduledGuildCount };
+    }
+    async refreshStatus(input) {
+        if (!this.discordToken)
+            throw new Error("Discord command reads are unavailable");
+        const baseline = (await this.#repository.getState(this.applicationId, input.guildId)) ??
+            (await this.#repository.ensureState({
+                applicationId: this.applicationId,
+                guildId: input.guildId,
+                setupState: "incomplete",
+            }));
+        const observed = await new REST({ version: "10" })
+            .setToken(this.discordToken)
+            .get(Routes.applicationGuildCommands(this.applicationId, input.guildId));
+        if (!Array.isArray(observed))
+            throw new Error("Discord returned an invalid command collection");
+        try {
+            await this.#repository.recordStatusRefresh({
+                applicationId: this.applicationId,
+                guildId: input.guildId,
+                installedRootCount: observed.length,
+                observedDefinitionHash: guildCommandDefinitionHash(observed),
+                expectedRevision: baseline.desiredRevision,
+                expectedUpdatedAt: baseline.updatedAt,
+                actorUserId: input.actorUserId,
+                correlationId: input.correlationId,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof GuildCommandRevisionConflictError))
+                throw error;
+        }
+        return this.getStatus(input.guildId);
+    }
+    async changeProfile(input) {
+        const idempotencyHash = createHash("sha256")
+            .update(`profile:${input.correlationId}`)
+            .digest("hex");
+        await this.#repository.changeVisibilityProfile({
+            applicationId: this.applicationId,
+            guildId: input.guildId,
+            profile: input.profile,
+            expectedRevision: input.expectedRevision,
+            idempotencyKey: `profile:${idempotencyHash}`,
+            actorUserId: input.actorUserId,
+            correlationId: input.correlationId,
+            summary: input.reasonSummary,
+        });
+        return this.getStatus(input.guildId);
+    }
+    async setMigrationHold(input) {
+        await this.#repository.setMigrationHold({
+            applicationId: this.applicationId,
+            ...input,
+        });
+        return this.getStatus(input.guildId);
+    }
+    async listHistory(input) {
+        const page = await this.#repository.listHistory({
+            applicationId: this.applicationId,
+            guildId: input.guildId,
+            ...(input.beforeEventId === undefined
+                ? {}
+                : { beforeEventId: input.beforeEventId }),
+            ...(input.since === undefined ? {} : { since: input.since }),
+            ...(input.limit === undefined ? {} : { limit: input.limit }),
+        });
+        return {
+            items: page.items.map(serializeHistory),
+            nextCursor: page.nextCursor?.toString() ?? null,
+        };
+    }
+    async getHealth() {
+        const workerHealth = this.workerHealth?.();
+        const health = workerHealth
+            ? await workerHealth
+            : {
+                ...(await this.#repository.getHealth()),
+                mode: "dry_run",
+                discordWritesEnabled: false,
+                workerRunning: false,
+                activeCount: 0,
+            };
+        return health;
+    }
+}
+function serializeState(state) {
+    return {
+        applicationId: state.applicationId,
+        guildId: state.guildId,
+        visibilityProfile: state.visibilityProfile,
+        desiredDefinitionHash: state.desiredDefinitionHash,
+        desiredRootCount: state.desiredRootCount,
+        desiredSubcommandCount: state.desiredSubcommandCount,
+        lastObservedDefinitionHash: state.lastObservedDefinitionHash,
+        installedRootCount: state.installedRootCount,
+        state: state.state,
+        desiredRevision: state.desiredRevision.toString(),
+        scheduledAt: iso(state.scheduledAt),
+        startedAt: iso(state.startedAt),
+        lastAttemptedAt: iso(state.lastAttemptedAt),
+        lastSuccessfulAt: iso(state.lastSuccessfulAt),
+        lastSafeCode: state.lastSafeCode,
+        setupState: state.setupState,
+        updatedAt: state.updatedAt.toISOString(),
+    };
+}
+function serializeRequest(request) {
+    return {
+        requestId: request.requestId,
+        source: request.source,
+        requestedRevision: request.requestedRevision.toString(),
+        notBefore: request.notBefore.toISOString(),
+        budgetClass: request.budgetClass,
+        status: request.status,
+        attemptCount: request.attemptCount,
+        attemptLimit: request.attemptLimit,
+        correlationId: request.correlationId,
+        lastSafeCode: request.lastSafeCode,
+        createdAt: request.createdAt.toISOString(),
+        updatedAt: request.updatedAt.toISOString(),
+    };
+}
+function serializeHistory(history) {
+    return {
+        eventId: history.eventId.toString(),
+        eventType: history.eventType,
+        summary: history.summary,
+        actorUserId: history.actorUserId,
+        moduleId: history.moduleId,
+        requestId: history.requestId,
+        correlationId: history.correlationId,
+        createdCount: history.createdCount,
+        updatedCount: history.updatedCount,
+        removedCount: history.removedCount,
+        createdCommands: history.createdCommands,
+        updatedCommands: history.updatedCommands,
+        removedCommands: history.removedCommands,
+        creationsUsed: history.creationsUsed,
+        resultState: history.resultState,
+        createdAt: history.createdAt.toISOString(),
+    };
+}
+function iso(value) {
+    return value?.toISOString() ?? null;
+}
+//# sourceMappingURL=guild-command-read-service.js.map

package/dist/guild-command-release.d.ts

@@ -0,0 +1,19 @@
+import { GuildCommandRepository, InstallationRepository, RuntimeStateRepository, type DatabasePool } from "@helyx/database";
+type ReleaseInstallationRepository = Pick<InstallationRepository, "listActiveGuilds">;
+type ReleaseCommandRepository = Pick<GuildCommandRepository, "getState" | "schedule">;
+type ReleaseRuntimeRepository = Pick<RuntimeStateRepository, "get" | "compareAndSet">;
+export declare function scheduleGuildCommandRelease(input: {
+    database: DatabasePool;
+    applicationId: string;
+    releaseId: string;
+    staggerMs?: number;
+    installations?: ReleaseInstallationRepository;
+    commands?: ReleaseCommandRepository;
+    runtime?: ReleaseRuntimeRepository;
+}): Promise<{
+    scheduled: number;
+    skippedIncomplete: number;
+    replay: boolean;
+}>;
+export {};
+//# sourceMappingURL=guild-command-release.d.ts.map

package/dist/guild-command-release.js

@@ -0,0 +1,47 @@
+import { GuildCommandRepository, InstallationRepository, RuntimeStateRepository, } from "@helyx/database";
+const RELEASE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const DEFAULT_STAGGER_MS = 600;
+const MAX_STAGGER_MS = 10 * 60 * 1_000;
+export async function scheduleGuildCommandRelease(input) {
+    if (!RELEASE_ID.test(input.releaseId))
+        throw new Error("Guild command release ID is invalid");
+    const markerKey = `guild-commands:release:${input.applicationId}:${input.releaseId}`;
+    const installations = input.installations ?? new InstallationRepository(input.database);
+    const commands = input.commands ?? new GuildCommandRepository(input.database);
+    const runtime = input.runtime ?? new RuntimeStateRepository(input.database);
+    if (await runtime.get(markerKey))
+        return { scheduled: 0, skippedIncomplete: 0, replay: true };
+    const guilds = await installations.listActiveGuilds();
+    const staggerMs = Math.max(0, input.staggerMs ?? DEFAULT_STAGGER_MS);
+    let scheduled = 0;
+    let skippedIncomplete = 0;
+    for (const guild of guilds) {
+        const state = await commands.getState(input.applicationId, guild.guildId);
+        if (state?.setupState !== "complete") {
+            skippedIncomplete += 1;
+            continue;
+        }
+        await commands.schedule({
+            applicationId: input.applicationId,
+            guildId: guild.guildId,
+            idempotencyKey: `release:${input.releaseId}:${guild.guildId}`,
+            source: "release_migration",
+            budgetClass: "system",
+            correlationId: `release:${input.releaseId}:${guild.guildId}`,
+            summary: "Helyx scheduled this server's command release update.",
+            delayMs: Math.min(scheduled * staggerMs, MAX_STAGGER_MS),
+        });
+        scheduled += 1;
+    }
+    await runtime.compareAndSet({
+        key: markerKey,
+        expectedVersion: null,
+        value: {
+            releaseId: input.releaseId,
+            scheduledGuilds: scheduled,
+            completedAt: new Date().toISOString(),
+        },
+    });
+    return { scheduled, skippedIncomplete, replay: false };
+}
+//# sourceMappingURL=guild-command-release.js.map

package/dist/guild-command-worker.d.ts

@@ -0,0 +1,49 @@
+import { GuildCommandRepository, type GuildCommandHealth, type GuildCommandRequestRecord } from "@helyx/database";
+import type { Logger, ModuleDefinition } from "@helyx/sdk";
+import type { Pool } from "pg";
+import { type GuildCommandDiff, type GuildCommandProjection } from "./guild-command-projection.js";
+import type { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
+export interface GuildCommandWorkerHealth extends GuildCommandHealth {
+    mode: "dry_run" | "live";
+    discordWritesEnabled: boolean;
+    workerRunning: boolean;
+    activeCount: number;
+}
+export declare class GuildCommandWorker {
+    #private;
+    constructor(input: {
+        database: Pool;
+        modules: readonly ModuleDefinition[];
+        logger: Logger;
+        workerId?: string;
+        fencingToken: bigint;
+        discord?: Pick<GuildCommandDiscordClient, "canWrite" | "observe" | "replace">;
+        internalGuildId?: string;
+        pollIntervalMs?: number;
+        leaseMs?: number;
+        claimLimit?: number;
+        concurrency?: number;
+        stopTimeoutMs?: number;
+    });
+    start(): void;
+    runOnce(): Promise<void>;
+    stop(): Promise<void>;
+    getHealth(): Promise<GuildCommandWorkerHealth>;
+}
+type LiveRepository = Pick<GuildCommandRepository, "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation">;
+export declare function reconcileLiveGuildCommands(input: {
+    repository: LiveRepository;
+    discord: Pick<GuildCommandDiscordClient, "observe" | "replace">;
+    request: GuildCommandRequestRecord;
+    projection: GuildCommandProjection;
+    workerId: string;
+    fencingToken: bigint;
+    leaseMs: number;
+    verificationDelayMs?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    outcome: "completed" | "stale" | "fenced";
+    diff: GuildCommandDiff;
+} | null>;
+export {};
+//# sourceMappingURL=guild-command-worker.d.ts.map