pi-roundtable 0.1.0

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

@@ -0,0 +1,183 @@
+import {
+	ChannelType,
+	type Guild,
+	type GuildBasedChannel,
+	type GuildMember,
+	PermissionFlagsBits,
+	PermissionsBitField,
+	type Role,
+} from "discord.js";
+import { messages } from "../i18n/index.ts";
+import { ChannelToolError } from "./channel-operations.ts";
+
+/** What both the owner and the bot hold in the server for each server-level tool. */
+export const SERVER_PERMISSIONS: Record<string, bigint[]> = {
+	discord_list_channels: [],
+	discord_list_roles: [],
+	discord_list_threads: [],
+	discord_find_members: [],
+	discord_create_channel: [PermissionFlagsBits.ManageChannels],
+	discord_create_role: [PermissionFlagsBits.ManageRoles],
+	discord_edit_role: [PermissionFlagsBits.ManageRoles],
+	discord_delete_role: [PermissionFlagsBits.ManageRoles],
+	discord_add_member_role: [PermissionFlagsBits.ManageRoles],
+	discord_remove_member_role: [PermissionFlagsBits.ManageRoles],
+	discord_set_nickname: [PermissionFlagsBits.ManageNicknames],
+	discord_timeout_member: [PermissionFlagsBits.ModerateMembers],
+	discord_kick_member: [PermissionFlagsBits.KickMembers],
+	discord_ban_member: [PermissionFlagsBits.BanMembers],
+	discord_unban_member: [PermissionFlagsBits.BanMembers],
+};
+
+export const CHANNEL_TYPES = {
+	text: ChannelType.GuildText,
+	voice: ChannelType.GuildVoice,
+	announcement: ChannelType.GuildAnnouncement,
+	category: ChannelType.GuildCategory,
+} as const;
+
+export const refuse = (code: string, detail: string) =>
+	new ChannelToolError(`${code}: ${detail}`);
+
+/** The owner outranks a role when the owner's highest role is above it, or the owner owns the server. */
+export function outranksRole(owner: GuildMember, role: Role): boolean {
+	return (
+		owner.guild.ownerId === owner.id ||
+		owner.roles.highest.comparePositionTo(role) > 0
+	);
+}
+
+export function outranksMember(
+	owner: GuildMember,
+	target: GuildMember,
+): boolean {
+	if (owner.guild.ownerId === owner.id) return target.id !== owner.id;
+	return (
+		target.id !== owner.guild.ownerId &&
+		owner.roles.highest.comparePositionTo(target.roles.highest) > 0
+	);
+}
+
+export function permissionFlags(names: unknown): bigint[] {
+	const list = (names ?? []) as string[];
+	for (const name of list) {
+		if (!Object.hasOwn(PermissionFlagsBits, name))
+			throw refuse("INVALID_PERMISSION", name);
+	}
+	return list.map(
+		(name) => PermissionFlagsBits[name as keyof typeof PermissionFlagsBits],
+	);
+}
+
+/** The owner's and the bot's standing in a server: who holds what, and who outranks whom. */
+export class OwnerAccess {
+	readonly #ownerId: string;
+	readonly #ownerName: string;
+
+	constructor(ownerId: string, ownerName: string) {
+		this.#ownerId = ownerId;
+		this.#ownerName = ownerName;
+	}
+
+	/**
+	 * The owner's and the bot's members, after checking both hold the permissions, in the
+	 * channel when one is given and in the server otherwise.
+	 */
+	async members(
+		guild: Guild,
+		needed: bigint[],
+		channel?: GuildBasedChannel,
+	): Promise<{ owner: GuildMember; bot: GuildMember }> {
+		const owner = await guild.members
+			.fetch({ user: this.#ownerId, force: true })
+			.catch(() => undefined);
+		if (!owner)
+			throw refuse(
+				"OWNER_NOT_IN_SERVER",
+				`${this.#ownerName} is not in that server`,
+			);
+		const bot = await guild.members.fetchMe({ force: true });
+		const has = (member: GuildMember) =>
+			(channel ? channel.permissionsFor(member) : member.permissions).has(
+				needed,
+			);
+		const names = new PermissionsBitField(needed).toArray().join(", ");
+		if (!has(owner))
+			throw refuse(
+				"OWNER_PERMISSION_MISSING",
+				`${this.#ownerName} lacks ${names} there`,
+			);
+		if (!has(bot))
+			throw refuse(
+				"BOT_PERMISSION_MISSING",
+				messages().refuseAssistantLacks(names),
+			);
+		return { owner, bot };
+	}
+
+	holdsAll(owner: GuildMember, permissions: bigint[]): void {
+		if (!owner.permissions.has(permissions))
+			throw refuse(
+				"OWNER_PERMISSION_MISSING",
+				`${this.#ownerName} does not hold every permission the role would grant`,
+			);
+	}
+
+	outranks(owner: GuildMember, member: GuildMember): void {
+		if (!outranksMember(owner, member))
+			throw refuse(
+				"HIERARCHY",
+				`that member is not below ${this.#ownerName}'s highest role`,
+			);
+	}
+
+	async role(guild: Guild, owner: GuildMember, roleId: unknown) {
+		const role = await guild.roles.fetch(String(roleId)).catch(() => null);
+		if (!role) throw refuse("UNKNOWN_ROLE", String(roleId));
+		if (!outranksRole(owner, role))
+			throw refuse(
+				"HIERARCHY",
+				`that role is not below ${this.#ownerName}'s highest role`,
+			);
+		return role;
+	}
+
+	async member(guild: Guild, userId: unknown) {
+		const member = await guild.members
+			.fetch({ user: String(userId), force: true })
+			.catch(() => undefined);
+		if (!member) throw refuse("UNKNOWN_MEMBER", String(userId));
+		return member;
+	}
+
+	async category(guild: Guild, parentId: string) {
+		const parent = await guild.channels.fetch(parentId).catch(() => null);
+		if (parent?.type !== ChannelType.GuildCategory)
+			throw refuse("INVALID_CHANNEL", "parentId is not a category there");
+		return parent;
+	}
+}
+
+/** A member's server permissions; an administrator holds them all. */
+export function permissionNames(member: GuildMember): string[] {
+	return member.permissions.has(PermissionFlagsBits.Administrator)
+		? ["Administrator"]
+		: member.permissions.toArray();
+}
+
+export function roleOptions(
+	args: Record<string, unknown>,
+	permissions: bigint[] | undefined,
+) {
+	return {
+		...(typeof args.name === "string" ? { name: args.name } : {}),
+		...(typeof args.color === "string"
+			? { colors: { primaryColor: args.color as `#${string}` } }
+			: {}),
+		...(typeof args.hoist === "boolean" ? { hoist: args.hoist } : {}),
+		...(typeof args.mentionable === "boolean"
+			? { mentionable: args.mentionable }
+			: {}),
+		...(permissions ? { permissions } : {}),
+	};
+}

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

@@ -0,0 +1,160 @@
+import {
+	type AnyThreadChannel,
+	ChannelType,
+	type Client,
+	type Guild,
+	type GuildMember,
+	PermissionFlagsBits,
+} from "discord.js";
+import { fetchManagedChannel, fetchOwnerChannel } from "./channel-executor.ts";
+import { type OwnerAccess, refuse } from "./owner-discord-access.ts";
+
+/** The owner's agent's thread operations, bounded by what both the owner and the bot may do. */
+export class OwnerThreads {
+	readonly #client: Client;
+	readonly #access: OwnerAccess;
+	readonly #ownerId: string;
+	/** The audit-log reason of an action taken without one of its own. */
+	readonly #reason: string;
+
+	constructor(
+		client: Client,
+		access: OwnerAccess,
+		ownerId: string,
+		reason: string,
+	) {
+		this.#client = client;
+		this.#access = access;
+		this.#ownerId = ownerId;
+		this.#reason = reason;
+	}
+
+	/**
+	 * Threads both can see: a private thread only when the owner may manage threads there,
+	 * since Discord shows it to its members alone otherwise.
+	 */
+	async list(
+		guild: Guild,
+		owner: GuildMember,
+		bot: GuildMember,
+		args: Record<string, unknown>,
+	) {
+		const parentId =
+			typeof args.parentId === "string" ? args.parentId : undefined;
+		let threads: AnyThreadChannel[];
+		if (args.archived === true) {
+			if (!parentId)
+				throw refuse("INVALID_ARGUMENT", "archived threads need parentId");
+			const parent = await fetchManagedChannel(this.#client, parentId);
+			if (parent.guildId !== guild.id)
+				throw refuse("INVALID_CHANNEL", "parentId is not in that server");
+			const fetched = await parent.threads.fetchArchived({ limit: 50 });
+			threads = [...fetched.threads.values()];
+		} else {
+			const fetched = await guild.channels.fetchActiveThreads();
+			threads = [...fetched.threads.values()].filter(
+				(t) => !parentId || t.parentId === parentId,
+			);
+		}
+		const sees = (member: GuildMember, thread: AnyThreadChannel) => {
+			const permissions = thread.permissionsFor(member);
+			return (
+				permissions.has(PermissionFlagsBits.ViewChannel) &&
+				(thread.type !== ChannelType.PrivateThread ||
+					permissions.has(PermissionFlagsBits.ManageThreads))
+			);
+		};
+		return threads
+			.filter((t) => sees(owner, t) && sees(bot, t))
+			.map((t) => ({
+				id: t.id,
+				name: t.name,
+				parentId: t.parentId,
+				private: t.type === ChannelType.PrivateThread,
+				archived: t.archived,
+				locked: t.locked,
+				messageCount: t.messageCount,
+				createdAt: t.createdAt?.toISOString() ?? null,
+			}));
+	}
+
+	async create(args: Record<string, unknown>) {
+		const parent = await fetchManagedChannel(
+			this.#client,
+			String(args.channelId),
+		);
+		const isPrivate = args.private === true;
+		if (isPrivate && (args.messageId || parent.type !== ChannelType.GuildText))
+			throw refuse(
+				"INVALID_ARGUMENT",
+				"a private thread starts on its own in a text channel",
+			);
+		await this.#access.members(
+			parent.guild,
+			[
+				PermissionFlagsBits.ViewChannel,
+				isPrivate
+					? PermissionFlagsBits.CreatePrivateThreads
+					: PermissionFlagsBits.CreatePublicThreads,
+				PermissionFlagsBits.SendMessagesInThreads,
+			],
+			parent,
+		);
+		const options = {
+			name: String(args.name),
+			...(typeof args.autoArchiveMinutes === "number"
+				? { autoArchiveDuration: args.autoArchiveMinutes }
+				: {}),
+			reason: typeof args.reason === "string" ? args.reason : this.#reason,
+		};
+		let thread: AnyThreadChannel;
+		if (typeof args.messageId === "string") {
+			const message = await parent.messages.fetch(args.messageId).catch(() => {
+				throw refuse("UNKNOWN_MESSAGE", String(args.messageId));
+			});
+			thread = await message.startThread(options);
+		} else if (isPrivate && parent.type === ChannelType.GuildText) {
+			thread = await parent.threads.create({
+				...options,
+				type: ChannelType.PrivateThread,
+			});
+			await thread.members.add(this.#ownerId);
+		} else {
+			thread = await parent.threads.create(options);
+		}
+		return {
+			id: thread.id,
+			name: thread.name,
+			parentId: thread.parentId,
+			private: isPrivate,
+		};
+	}
+
+	async edit(args: Record<string, unknown>) {
+		const thread = await fetchOwnerChannel(this.#client, String(args.threadId));
+		if (!thread.isThread())
+			throw refuse("INVALID_CHANNEL", "threadId is not a thread");
+		await this.#access.members(
+			thread.guild,
+			[PermissionFlagsBits.ViewChannel, PermissionFlagsBits.ManageThreads],
+			thread,
+		);
+		await thread.edit({
+			...(typeof args.name === "string" ? { name: args.name } : {}),
+			...(typeof args.archived === "boolean"
+				? { archived: args.archived }
+				: {}),
+			...(typeof args.locked === "boolean" ? { locked: args.locked } : {}),
+			...(typeof args.autoArchiveMinutes === "number"
+				? { autoArchiveDuration: args.autoArchiveMinutes }
+				: {}),
+			reason: typeof args.reason === "string" ? args.reason : this.#reason,
+		});
+		return {
+			id: thread.id,
+			name: thread.name,
+			archived: thread.archived,
+			locked: thread.locked,
+		};
+	}
+}

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

@@ -0,0 +1,325 @@
+import { describe, expect, test } from "bun:test";
+import { ChannelType, type Client, PermissionFlagsBits } from "discord.js";
+import { DiscordOwnerOps } from "./owner-discord.ts";
+
+const OWNER = "100";
+const BOT = "200";
+const {
+	KickMembers,
+	ManageNicknames,
+	ManageRoles,
+	Administrator,
+	ViewChannel,
+	ManageThreads,
+	CreatePrivateThreads,
+	SendMessagesInThreads,
+} = PermissionFlagsBits;
+
+class FakeRole {
+	constructor(
+		readonly id: string,
+		readonly position: number,
+	) {}
+	comparePositionTo(other: FakeRole): number {
+		return this.position - other.position;
+	}
+}
+
+/** A member with a fixed permission set, a highest role, and recorded actions. */
+class FakeMember {
+	actions: string[] = [];
+	readonly roles: {
+		highest: FakeRole;
+		add: (role: FakeRole) => Promise<void>;
+	};
+	readonly permissions: { has: (needed: bigint | bigint[]) => boolean };
+	constructor(
+		readonly id: string,
+		readonly guild: FakeGuild,
+		rank: number,
+		granted: bigint[],
+	) {
+		this.roles = {
+			highest: new FakeRole(`r${id}`, rank),
+			add: async (role) => {
+				this.actions.push(`add ${role.id}`);
+			},
+		};
+		this.permissions = {
+			has: (needed) =>
+				granted.includes(Administrator) ||
+				[needed].flat().every((p) => granted.includes(p)),
+		};
+	}
+	async kick(): Promise<void> {
+		this.actions.push("kick");
+	}
+	async setNickname(nickname: string | null): Promise<void> {
+		this.actions.push(`nick ${nickname}`);
+	}
+}
+
+class FakeGuild {
+	readonly id = "1";
+	ownerId = "999";
+	readonly people = new Map<string, FakeMember>();
+	readonly roleList = new Map<string, FakeRole>();
+	readonly members = {
+		fetch: async ({ user }: { user: string }) => {
+			const member = this.people.get(user);
+			if (!member) throw new Error("Unknown Member");
+			return member;
+		},
+		fetchMe: async () => this.people.get(BOT),
+	};
+	readonly roles = {
+		fetch: async (id: string) => this.roleList.get(id) ?? null,
+	};
+	readonly threadList = new Map<string, FakeThread>();
+	readonly channels = {
+		fetchActiveThreads: async () => ({ threads: this.threadList }),
+	};
+	add(id: string, rank: number, granted: bigint[]): FakeMember {
+		const member = new FakeMember(id, this, rank, granted);
+		this.people.set(id, member);
+		return member;
+	}
+}
+
+/** A thread whose permissions are its members' server permissions. */
+class FakeThread {
+	edits: object[] = [];
+	added: string[] = [];
+	readonly parentId = "50";
+	readonly guildId: string;
+	archived = false;
+	locked = false;
+	readonly messageCount = 0;
+	readonly createdAt = new Date(0);
+	readonly members = {
+		add: async (id: string) => {
+			this.added.push(id);
+		},
+	};
+	constructor(
+		readonly id: string,
+		readonly guild: FakeGuild,
+		readonly type: ChannelType,
+		readonly name = "t",
+	) {
+		this.guildId = guild.id;
+	}
+	isThread() {
+		return true;
+	}
+	permissionsFor(member: FakeMember) {
+		return member.permissions;
+	}
+	async edit(options: object) {
+		this.edits.push(options);
+	}
+}
+
+/** A text channel whose new threads are recorded. */
+class FakeTextChannel {
+	readonly id = "50";
+	readonly type = ChannelType.GuildText;
+	readonly guildId: string;
+	created: object[] = [];
+	readonly threads = {
+		create: async (options: { name: string; type?: ChannelType }) => {
+			this.created.push(options);
+			return new FakeThread(
+				"60",
+				this.guild,
+				options.type ?? ChannelType.PublicThread,
+				options.name,
+			);
+		},
+	};
+	constructor(readonly guild: FakeGuild) {
+		this.guildId = guild.id;
+	}
+	isThread() {
+		return false;
+	}
+	permissionsFor(member: FakeMember) {
+		return member.permissions;
+	}
+}
+
+function setup(ownerGrants: bigint[], botGrants: bigint[]) {
+	const guild = new FakeGuild();
+	const owner = guild.add(OWNER, 10, ownerGrants);
+	const bot = guild.add(BOT, 20, botGrants);
+	const guest = guild.add("300", 5, []);
+	const text = new FakeTextChannel(guild);
+	const channels = new Map<string, unknown>([["50", text]]);
+	const client = {
+		isReady: () => true,
+		channels: { fetch: async (id: string) => channels.get(id) ?? null },
+		guilds: {
+			fetch: async (id: string) => {
+				if (id !== guild.id) throw new Error("Unknown Guild");
+				return guild;
+			},
+		},
+	} as unknown as Client;
+	return {
+		ops: new DiscordOwnerOps(client, OWNER),
+		guild,
+		owner,
+		bot,
+		guest,
+		text,
+		channels,
+	};
+}
+
+const kick = (userId: string) => ({ guildId: "1", userId });
+
+describe("DiscordOwnerOps", () => {
+	test("a kick runs when both hold the permission and the owner outranks the member", async () => {
+		const { ops, guest } = setup([KickMembers], [KickMembers]);
+		expect(await ops.run("discord_kick_member", kick("300"))).toEqual({
+			userId: "300",
+			kicked: true,
+		});
+		expect(guest.actions).toEqual(["kick"]);
+	});
+
+	test.each([
+		["the owner lacks it", [], [KickMembers], "OWNER_PERMISSION_MISSING"],
+		["the bot lacks it", [KickMembers], [], "BOT_PERMISSION_MISSING"],
+	])(
+		"a kick is refused when %s",
+		async (_name, ownerGrants, botGrants, code) => {
+			const { ops, guest } = setup(ownerGrants, botGrants);
+			await expect(ops.run("discord_kick_member", kick("300"))).rejects.toThrow(
+				code,
+			);
+			expect(guest.actions).toEqual([]);
+		},
+	);
+
+	test("a member at or above the owner's highest role is refused unless the owner owns the server", async () => {
+		const { ops, guild, guest } = setup([KickMembers], [KickMembers]);
+		guest.roles.highest = new FakeRole("rtop", 10);
+		await expect(ops.run("discord_kick_member", kick("300"))).rejects.toThrow(
+			"HIERARCHY",
+		);
+		guild.ownerId = OWNER;
+		await ops.run("discord_kick_member", kick("300"));
+		expect(guest.actions).toEqual(["kick"]);
+	});
+
+	test("the owner must be in the server", async () => {
+		const { ops, guild } = setup([KickMembers], [KickMembers]);
+		guild.people.delete(OWNER);
+		await expect(ops.run("discord_kick_member", kick("300"))).rejects.toThrow(
+			"OWNER_NOT_IN_SERVER",
+		);
+	});
+
+	test("a role above the owner cannot be given", async () => {
+		const { ops, guild, guest } = setup([ManageRoles], [ManageRoles]);
+		guild.roleList.set("low", new FakeRole("low", 3));
+		guild.roleList.set("high", new FakeRole("high", 15));
+		const give = (roleId: string) =>
+			ops.run("discord_add_member_role", {
+				guildId: "1",
+				userId: "300",
+				roleId,
+			});
+		await give("low");
+		await expect(give("high")).rejects.toThrow("HIERARCHY");
+		expect(guest.actions).toEqual(["add low"]);
+	});
+
+	test("the owner may rename the assistant even though it ranks higher", async () => {
+		const { ops, bot } = setup([ManageNicknames], [ManageNicknames]);
+		await ops.run("discord_set_nickname", {
+			guildId: "1",
+			userId: BOT,
+			nickname: "Pika the Crow",
+		});
+		expect(bot.actions).toEqual(["nick Pika the Crow"]);
+	});
+});
+
+describe("threads", () => {
+	const threadMaker = [
+		ViewChannel,
+		CreatePrivateThreads,
+		SendMessagesInThreads,
+	];
+
+	test("a private thread starts on its own and has the owner added", async () => {
+		const { ops, text } = setup(threadMaker, threadMaker);
+		expect(
+			await ops.run("discord_create_thread", {
+				channelId: "50",
+				name: "plans",
+				private: true,
+			}),
+		).toEqual({ id: "60", name: "plans", parentId: "50", private: true });
+		expect(text.created).toMatchObject([
+			{ name: "plans", type: ChannelType.PrivateThread },
+		]);
+	});
+
+	test("a private thread from a message is refused before anything is made", async () => {
+		const { ops, text } = setup(threadMaker, threadMaker);
+		await expect(
+			ops.run("discord_create_thread", {
+				channelId: "50",
+				name: "x",
+				messageId: "70",
+				private: true,
+			}),
+		).rejects.toThrow("INVALID_ARGUMENT");
+		expect(text.created).toEqual([]);
+	});
+
+	test("editing a thread needs Manage Threads from both", async () => {
+		const { ops, guild, channels } = setup([ViewChannel], [Administrator]);
+		const thread = new FakeThread("61", guild, ChannelType.PublicThread);
+		channels.set("61", thread);
+		await expect(
+			ops.run("discord_edit_thread", { threadId: "61", archived: true }),
+		).rejects.toThrow("OWNER_PERMISSION_MISSING");
+		expect(thread.edits).toEqual([]);
+
+		const both = setup([ViewChannel, ManageThreads], [Administrator]);
+		const shared = new FakeThread("62", both.guild, ChannelType.PublicThread);
+		both.channels.set("62", shared);
+		await both.ops.run("discord_edit_thread", {
+			threadId: "62",
+			archived: true,
+		});
+		expect(shared.edits).toMatchObject([{ archived: true }]);
+	});
+
+	test("private threads are listed only when the owner may manage threads", async () => {
+		const list = async (ownerGrants: bigint[]) => {
+			const { ops, guild } = setup(ownerGrants, [Administrator]);
+			guild.threadList.set(
+				"63",
+				new FakeThread("63", guild, ChannelType.PublicThread, "open"),
+			);
+			guild.threadList.set(
+				"64",
+				new FakeThread("64", guild, ChannelType.PrivateThread, "secret"),
+			);
+			const threads = (await ops.run("discord_list_threads", {
+				guildId: "1",
+			})) as { name: string }[];
+			return threads.map((t) => t.name);
+		};
+		expect(await list([ViewChannel])).toEqual(["open"]);
+		expect(await list([ViewChannel, ManageThreads])).toEqual([
+			"open",
+			"secret",
+		]);
+	});
+});