pi-roundtable 0.1.0

package/src/core/discord/owner-cards.ts

@@ -0,0 +1,463 @@
+import { randomUUID } from "node:crypto";
+import {
+	ActionRowBuilder,
+	ButtonBuilder,
+	ButtonStyle,
+	type Interaction,
+	LabelBuilder,
+	MessageFlags,
+	ModalBuilder,
+	StringSelectMenuBuilder,
+	TextDisplayBuilder,
+	TextInputBuilder,
+	TextInputStyle,
+} from "discord.js";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type {
+	Approval,
+	OwnerAnswer,
+	OwnerPrompts,
+	OwnerQuestion,
+} from "../domain/owner-prompts.ts";
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+import {
+	type Speaker,
+	type SpeakerPolicy,
+	type Tier,
+	tierAtLeast,
+} from "../speakers.ts";
+import type { InteractionModule } from "./interaction-module.ts";
+import { ownerPanel, type PanelContent, plain } from "./owner-panel.ts";
+
+export const CARD_PREFIX = "roundtable:card:";
+/** An unanswered card expires after this long. */
+export const CARD_TIMEOUT_MS = 30 * 60_000;
+const OTHER = "other";
+const TEXT_FIELD = "text";
+
+/** A card's message: the panel, led by a mention of the owner in a thread. */
+export type CardPayload = Omit<
+	ReturnType<typeof ownerPanel>,
+	"components" | "allowedMentions"
+> & {
+	components: (
+		| ReturnType<typeof ownerPanel>["components"][number]
+		| TextDisplayBuilder
+	)[];
+	allowedMentions: { parse?: never[]; users?: string[] };
+};
+
+/** The posted card, which is edited to show how it ended. */
+export interface CardMessage {
+	edit(payload: CardPayload): Promise<unknown>;
+}
+
+/** Where a channel's cards are posted. */
+export interface CardChannel {
+	send(payload: CardPayload): Promise<CardMessage>;
+	/** A thread, where the owner is mentioned so he hears of the card; a channel never mentions him. */
+	thread?: boolean;
+}
+
+export interface OwnerCardsOptions {
+	ownerId: string;
+	/** Decides who holds a tier, for cards that lower tiers may answer; without it only the owner answers. */
+	speakers?: SpeakerPolicy;
+	/** The Discord channel by id; throws when it cannot take messages. */
+	channel(channelId: string): Promise<CardChannel>;
+	logger: Logger;
+	/** CARD_TIMEOUT_MS by default. */
+	timeoutMs?: number;
+}
+
+type Rows = NonNullable<Parameters<typeof ownerPanel>[0]["rows"]>;
+
+/** One open card: how it looks, and how it ends. */
+interface OpenCard {
+	title: string;
+	sections: string[];
+	/** The card's controls, disabled once it has ended. */
+	rows(disabled: boolean): Rows;
+	/** Ends the card with its answer; the answering interaction shows the outcome. */
+	end(value: unknown): void;
+	question?: OwnerQuestion;
+	/** Options chosen together with "Other…", kept while its form is open. */
+	picked?: string[];
+	/** Posted in a thread, so it leads with the mention of who may answer. */
+	mention?: boolean;
+	/** Who may answer, and what to tell someone else who presses it. */
+	audience: Audience;
+}
+
+/** The people a card is for. */
+interface Audience {
+	allows(user: { id: string; roleIds: readonly string[] }): boolean;
+	/** The user the card mentions in a thread. */
+	mentionId: string;
+	/** Shown on the card. */
+	note: string;
+	refusal: string;
+}
+
+/**
+ * The owner's cards in the assistant's channels: approvals of held actions and ask_user questions,
+ * answered with buttons, a menu, or a form. Only the owner may answer; an unanswered card
+ * expires after 30 minutes and a stopped turn cancels it. Open cards live in memory, so a
+ * restart abandons them; pressing one then says it no longer works.
+ */
+export class OwnerCards implements InteractionModule {
+	readonly #options: OwnerCardsOptions;
+	readonly #open = new Map<string, OpenCard>();
+
+	constructor(options: OwnerCardsOptions) {
+		this.#options = options;
+	}
+
+	commands() {
+		return [];
+	}
+
+	/** The channel's cards; undefined for a conversation outside Discord. */
+	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined {
+		if (!channel.startsWith("discord:")) return undefined;
+		const channelId = channel.slice("discord:".length);
+		return {
+			confirm: (title, message, signal, minTier = "owner") =>
+				this.#post<Approval>(channelId, signal, "expired", "cancelled", {
+					audience: this.#approvers(minTier, speaker),
+					title,
+					sections: [message],
+					rows: (id, disabled) => [
+						new ActionRowBuilder<ButtonBuilder>().addComponents(
+							new ButtonBuilder()
+								.setCustomId(`${CARD_PREFIX}${id}:yes`)
+								.setLabel(messages().cardRunLabel)
+								.setEmoji("✅")
+								.setStyle(ButtonStyle.Success)
+								.setDisabled(disabled),
+							new ButtonBuilder()
+								.setCustomId(`${CARD_PREFIX}${id}:no`)
+								.setLabel(messages().cardCancelLabel)
+								.setEmoji("❌")
+								.setStyle(ButtonStyle.Secondary)
+								.setDisabled(disabled),
+						),
+					],
+					footer: messages().cardApprovalFooter,
+				}),
+			ask: (title, question, signal) =>
+				this.#post<OwnerAnswer | undefined>(
+					channelId,
+					signal,
+					undefined,
+					undefined,
+					{
+						audience: this.#asker(speaker),
+						title,
+						sections: [question.question],
+						question,
+						rows: (id, disabled) => askRows(id, question, disabled),
+						footer: messages().cardQuestionFooter,
+					},
+				),
+		};
+	}
+
+	/** Posts a card and resolves with its answer, `expired`, or `cancelled`. */
+	#post<T>(
+		channelId: string,
+		signal: AbortSignal | undefined,
+		expired: T,
+		cancelled: T,
+		card: {
+			audience: Audience;
+			title: string;
+			sections: string[];
+			question?: OwnerQuestion;
+			rows(id: string, disabled: boolean): Rows;
+			footer: string;
+		},
+	): Promise<T> {
+		const { logger, timeoutMs = CARD_TIMEOUT_MS } = this.#options;
+		if (signal?.aborted) return Promise.resolve(cancelled);
+		const id = randomUUID();
+		const sections = [
+			...card.sections,
+			...(card.audience.note ? [card.audience.note] : []),
+		];
+		return new Promise<T>((resolve) => {
+			let message: CardMessage | undefined;
+			let finish: string | undefined;
+			const settle = (value: T, outcome: string | undefined) => {
+				if (!this.#open.delete(id)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", abort);
+				// A card ended by an answer is edited by the answering interaction.
+				if (outcome !== undefined) {
+					finish = outcome;
+					void message
+						?.edit(view(outcome))
+						.catch((error: unknown) =>
+							logger.warn({ channelId, err: error }, "card not closed"),
+						);
+				}
+				resolve(value);
+			};
+			const view = (footer: string, disabled = true) =>
+				this.#panel(
+					{
+						title: card.title,
+						sections,
+						rows: card.rows(id, disabled),
+						footer,
+					},
+					open.mention === true,
+					card.audience.mentionId,
+				);
+			const abort = () => settle(cancelled, messages().cardStopped);
+			const timer = setTimeout(
+				() => settle(expired, messages().cardExpired),
+				timeoutMs,
+			);
+			signal?.addEventListener("abort", abort, { once: true });
+			const open: OpenCard = {
+				title: card.title,
+				sections,
+				rows: (disabled) => card.rows(id, disabled),
+				audience: card.audience,
+				end: (value) => settle(value as T, undefined),
+				...(card.question ? { question: card.question } : {}),
+			};
+			this.#open.set(id, open);
+			this.#options
+				.channel(channelId)
+				.then((channel) => {
+					open.mention = channel.thread === true;
+					return channel.send(view(card.footer, false));
+				})
+				.then((posted) => {
+					message = posted;
+					// Ended while it was being posted.
+					if (finish !== undefined) void posted.edit(view(finish));
+				})
+				.catch((error: unknown) => {
+					logger.warn({ channelId, err: error }, "card not posted");
+					settle(expired, undefined);
+				});
+		});
+	}
+
+	/** The card's panel; in a thread it leads with the mention of who may answer. */
+	#panel(content: PanelContent, mention: boolean, userId: string): CardPayload {
+		const panel = ownerPanel(content);
+		if (!mention) return panel;
+		return {
+			...panel,
+			components: [
+				new TextDisplayBuilder().setContent(`<@${userId}>`),
+				...panel.components,
+			],
+			allowedMentions: { users: [userId] },
+		};
+	}
+
+	/** An approval is for the speakers whose tier holds the tool, the owner alone by default. */
+	#approvers(minTier: Tier, speaker: Speaker | undefined): Audience {
+		const { ownerId, speakers } = this.#options;
+		const mentionId =
+			speaker && tierAtLeast(speaker.tier, minTier) ? speaker.id : ownerId;
+		if (minTier === "owner" || !speakers)
+			return {
+				allows: (user) => user.id === ownerId,
+				mentionId: ownerId,
+				note: "",
+				refusal: messages().cardOwnerOnly,
+			};
+		return {
+			allows: (user) => {
+				const who = speakers.resolve({ ...user, name: "" });
+				return who !== undefined && tierAtLeast(who.tier, minTier);
+			},
+			mentionId,
+			note: messages().cardApproversNote(minTier),
+			refusal: messages().cardApproversRefusal(minTier),
+		};
+	}
+
+	/** A question is for the speaker whose turn asks it, and for the owner. */
+	#asker(speaker: Speaker | undefined): Audience {
+		const { ownerId } = this.#options;
+		if (!speaker || speaker.id === ownerId)
+			return {
+				allows: (user) => user.id === ownerId,
+				mentionId: ownerId,
+				note: "",
+				refusal: messages().cardOwnerOnly,
+			};
+		return {
+			allows: (user) => user.id === speaker.id || user.id === ownerId,
+			mentionId: speaker.id,
+			note: messages().cardAskerNote(speaker.id),
+			refusal: messages().cardAskerRefusal,
+		};
+	}
+
+	async handle(interaction: Interaction): Promise<boolean> {
+		if (
+			!(
+				interaction.isButton() ||
+				interaction.isStringSelectMenu() ||
+				interaction.isModalSubmit()
+			) ||
+			!interaction.customId.startsWith(CARD_PREFIX)
+		)
+			return false;
+		const [id = "", action = ""] = interaction.customId
+			.slice(CARD_PREFIX.length)
+			.split(":");
+		const card = this.#open.get(id);
+		if (!card) {
+			await interaction.reply({
+				content: messages().cardInactive,
+				flags: MessageFlags.Ephemeral,
+			});
+			return true;
+		}
+		const { member } = interaction;
+		const roleIds =
+			member && "cache" in member.roles ? [...member.roles.cache.keys()] : [];
+		if (!card.audience.allows({ id: interaction.user.id, roleIds })) {
+			await interaction.reply({
+				content: card.audience.refusal,
+				flags: MessageFlags.Ephemeral,
+			});
+			return true;
+		}
+		const closed = (outcome: string) =>
+			this.#panel(
+				{
+					title: card.title,
+					sections: card.sections,
+					rows: card.rows(true),
+					footer: outcome,
+				},
+				card.mention === true,
+				card.audience.mentionId,
+			);
+		if (interaction.isButton() && (action === "yes" || action === "no")) {
+			const approved = action === "yes";
+			card.end(approved ? "approved" : "declined");
+			await interaction.update(
+				closed(approved ? messages().cardApproved : messages().cardDeclined),
+			);
+			return true;
+		}
+		const question = card.question;
+		if (!question) return true;
+		if (interaction.isButton() && action === "write") {
+			card.picked = [];
+			await interaction.showModal(answerModal(id));
+			return true;
+		}
+		if (interaction.isStringSelectMenu() && action === "pick") {
+			const values = interaction.values;
+			const choices = question.options
+				.filter((_option, i) => values.includes(String(i)))
+				.map((option) => option.label);
+			if (values.includes(OTHER)) {
+				card.picked = choices;
+				await interaction.showModal(answerModal(id));
+				return true;
+			}
+			const answer = { choices };
+			card.end(answer);
+			await interaction.update(closed(answeredLine(answer)));
+			return true;
+		}
+		if (interaction.isModalSubmit() && action === "text") {
+			const answer = {
+				choices: card.picked ?? [],
+				text: interaction.fields.getTextInputValue(TEXT_FIELD),
+			};
+			card.end(answer);
+			if (interaction.isFromMessage())
+				await interaction.update(closed(answeredLine(answer)));
+			else await interaction.deferUpdate();
+			return true;
+		}
+		return true;
+	}
+}
+
+/** A question's controls: a menu of its options, or a button that opens the answer form. */
+function askRows(id: string, question: OwnerQuestion, disabled: boolean): Rows {
+	if (question.options.length === 0)
+		return [
+			new ActionRowBuilder<ButtonBuilder>().addComponents(
+				new ButtonBuilder()
+					.setCustomId(`${CARD_PREFIX}${id}:write`)
+					.setLabel(messages().cardAnswerLabel)
+					.setStyle(ButtonStyle.Primary)
+					.setDisabled(disabled),
+			),
+		];
+	// Discord menus take 25 options; "Other…" takes the last place when the options fill it.
+	const options = question.options
+		.slice(0, question.allowOther ? 24 : 25)
+		.map((option, i) => ({
+			label: option.label.slice(0, 100),
+			value: String(i),
+			...(option.description
+				? { description: option.description.slice(0, 100) }
+				: {}),
+		}));
+	if (question.allowOther)
+		options.push({
+			label: messages().cardOtherLabel,
+			value: OTHER,
+			description: messages().cardOtherDescription,
+		});
+	return [
+		new ActionRowBuilder<StringSelectMenuBuilder>().addComponents(
+			new StringSelectMenuBuilder()
+				.setCustomId(`${CARD_PREFIX}${id}:pick`)
+				.setPlaceholder(
+					question.multi
+						? messages().cardPickManyPlaceholder
+						: messages().cardPickOnePlaceholder,
+				)
+				.setMinValues(1)
+				.setMaxValues(question.multi ? options.length : 1)
+				.addOptions(options)
+				.setDisabled(disabled),
+		),
+	];
+}
+
+function answerModal(id: string): ModalBuilder {
+	return new ModalBuilder()
+		.setCustomId(`${CARD_PREFIX}${id}:text`)
+		.setTitle(messages().cardModalTitle)
+		.addLabelComponents(
+			new LabelBuilder()
+				.setLabel(messages().cardModalField)
+				.setTextInputComponent(
+					new TextInputBuilder()
+						.setCustomId(TEXT_FIELD)
+						.setStyle(TextInputStyle.Paragraph)
+						.setRequired(true)
+						.setMaxLength(1000),
+				),
+		);
+}
+
+function answeredLine(answer: OwnerAnswer): string {
+	const parts = [
+		...answer.choices.map(plain),
+		...(answer.text !== undefined
+			? [messages().cardQuote(plain(answer.text))]
+			: []),
+	];
+	return messages().cardAnswered(parts);
+}

package/src/core/discord/owner-command.ts

@@ -0,0 +1,126 @@
+import {
+	type AutocompleteInteraction,
+	type ChatInputCommandInteraction,
+	type Interaction,
+	InteractionContextType,
+	MessageFlags,
+	SlashCommandSubcommandGroupBuilder,
+} from "discord.js";
+import type { CommandRoot, RootOption } from "../contract/discord.ts";
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+import type { InteractionModule } from "./interaction-module.ts";
+import { ephemeralPanel, OwnerFacingError, ownerPanel } from "./owner-panel.ts";
+
+/** The owner's single control command, such as `/roundtable`, every feature adds its subcommands to. */
+export function ownerRootCommand(name: string): CommandRoot {
+	return {
+		name,
+		description: messages().ownerRootDescription,
+		contexts: [InteractionContextType.Guild, InteractionContextType.BotDM],
+	};
+}
+
+/** A subcommand group as the JSON the root command carries. */
+export const groupOption = (
+	build: (
+		group: SlashCommandSubcommandGroupBuilder,
+	) => SlashCommandSubcommandGroupBuilder,
+): RootOption => build(new SlashCommandSubcommandGroupBuilder()).toJSON();
+
+/**
+ * Only the owner may use the root command, checked by user ID; every answer is visible only to him,
+ * and a failure becomes a panel instead of a hanging interaction.
+ */
+// pi-lens-ignore: large-class — two methods: the owner check and the failure panel
+export class OwnerGuard {
+	readonly #ownerId: string;
+	readonly #logger: Logger;
+	/** The name of the root command the guard serves, without the slash. */
+	readonly root: string;
+
+	constructor(ownerId: string, logger: Logger, root: string) {
+		this.#ownerId = ownerId;
+		this.#logger = logger;
+		this.root = root;
+	}
+
+	isOwner(interaction: Interaction): boolean {
+		return interaction.user.id === this.#ownerId;
+	}
+
+	/** Runs a handler; failures become a panel instead of a hanging interaction. */
+	async run(interaction: Interaction, run: () => Promise<void>): Promise<void> {
+		try {
+			await run();
+		} catch (error) {
+			const owned = error instanceof OwnerFacingError;
+			if (!owned) this.#logger.error({ err: error }, "owner command failed");
+			if (!interaction.isRepliable()) return;
+			const text = messages();
+			const panel = {
+				title: owned ? text.ownerFailedTitle : text.ownerErrorTitle,
+				sections: [owned ? error.message : text.ownerErrorBody],
+			};
+			if (interaction.deferred || interaction.replied)
+				await interaction.editReply(ownerPanel(panel));
+			else await interaction.reply(ephemeralPanel(panel));
+		}
+	}
+}
+
+/** One feature's part of the root command. */
+export interface OwnerCommandHandlers {
+	/** Whether a root subcommand, in its group or null at the top level, is this feature's. */
+	owns(group: string | null, subcommand: string): boolean;
+	autocomplete?(interaction: AutocompleteInteraction): Promise<void>;
+	/** An answer that must be the interaction's first, such as a form; true when it answered. */
+	open?(interaction: ChatInputCommandInteraction): Promise<boolean>;
+	/** Answers a subcommand; the reply is already deferred and ephemeral. */
+	command(interaction: ChatInputCommandInteraction): Promise<void>;
+	/** Buttons, menus, and forms the feature posted; true when it handled one. */
+	component?(interaction: Interaction): Promise<boolean>;
+}
+
+const refusal = () =>
+	ephemeralPanel({
+		title: messages().ownerRefusalTitle,
+		sections: [messages().ownerRefusalBody],
+	});
+
+/** Answers a feature's root subcommands and components, for the owner only. */
+export function ownerCommandModule(
+	guard: OwnerGuard,
+	handlers: OwnerCommandHandlers,
+): InteractionModule {
+	const owned = (
+		interaction: AutocompleteInteraction | ChatInputCommandInteraction,
+	) =>
+		interaction.commandName === guard.root &&
+		handlers.owns(
+			interaction.options.getSubcommandGroup(),
+			interaction.options.getSubcommand(false) ?? "",
+		);
+	return {
+		commands: () => [],
+		async handle(interaction) {
+			if (interaction.isAutocomplete()) {
+				if (!owned(interaction)) return false;
+				if (!guard.isOwner(interaction)) await interaction.respond([]);
+				else await handlers.autocomplete?.(interaction);
+				return true;
+			}
+			if (await handlers.component?.(interaction)) return true;
+			if (!interaction.isChatInputCommand() || !owned(interaction))
+				return false;
+			if (!guard.isOwner(interaction)) {
+				await interaction.reply(refusal());
+				return true;
+			}
+			if (await handlers.open?.(interaction)) return true;
+			await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+			await guard.run(interaction, () => handlers.command(interaction));
+			return true;
+		},
+	};
+}