pi-roundtable 0.1.0

package/src/cli/discord-api.ts

@@ -0,0 +1,96 @@
+import { PermissionFlagsBits, PermissionsBitField } from "discord.js";
+import type { Http, HttpResponse } from "./http.ts";
+
+const API = "https://discord.com/api/v10";
+
+/** What the bot needs in the entry channel, and why; the doctor names any it lacks. */
+export const REQUIRED_PERMISSIONS = [
+	["ViewChannel", "see the channel"],
+	["SendMessages", "answer in it"],
+	["SendMessagesInThreads", "answer in threads"],
+	["ReadMessageHistory", "read what was said before"],
+	["EmbedLinks", "post cards"],
+	["AttachFiles", "post pictures and files"],
+	["PinMessages", "pin the dashboard"],
+	["CreatePublicThreads", "open threads for background reports"],
+	["ManageChannels", "create the agents' channels"],
+	["ManageWebhooks", "let each agent speak under its own name"],
+] as const satisfies readonly (readonly [
+	keyof typeof PermissionFlagsBits,
+	string,
+])[];
+
+/** The permission integer an invitation asks for. */
+export const INVITE_PERMISSIONS = REQUIRED_PERMISSIONS.reduce(
+	(bits, [name]) => bits | PermissionFlagsBits[name],
+	0n,
+);
+
+export function inviteUrl(botId: string): string {
+	return `https://discord.com/oauth2/authorize?client_id=${botId}&scope=bot+applications.commands&permissions=${INVITE_PERMISSIONS}`;
+}
+
+interface Role {
+	id: string;
+	permissions: string;
+}
+
+interface Overwrite {
+	id: string;
+	type: number;
+	allow: string;
+	deny: string;
+}
+
+/** What Discord grants `botId` in a channel: the guild's roles, then the channel's overwrites, as Discord documents. */
+export function channelPermissions(input: {
+	botId: string;
+	guildId: string;
+	ownerId: string;
+	roles: readonly Role[];
+	memberRoles: readonly string[];
+	overwrites: readonly Overwrite[];
+}): PermissionsBitField {
+	if (input.botId === input.ownerId)
+		return new PermissionsBitField(PermissionsBitField.All);
+	let bits = 0n;
+	for (const role of input.roles)
+		if (role.id === input.guildId || input.memberRoles.includes(role.id))
+			bits |= BigInt(role.permissions);
+	if (bits & PermissionFlagsBits.Administrator)
+		return new PermissionsBitField(PermissionsBitField.All);
+	const apply = (allow: bigint, deny: bigint) => {
+		bits = (bits & ~deny) | allow;
+	};
+	const pick = (match: (overwrite: Overwrite) => boolean) => {
+		let allow = 0n;
+		let deny = 0n;
+		for (const overwrite of input.overwrites.filter(match)) {
+			allow |= BigInt(overwrite.allow);
+			deny |= BigInt(overwrite.deny);
+		}
+		apply(allow, deny);
+	};
+	pick((overwrite) => overwrite.id === input.guildId);
+	pick(
+		(overwrite) =>
+			overwrite.type === 0 && input.memberRoles.includes(overwrite.id),
+	);
+	pick((overwrite) => overwrite.type === 1 && overwrite.id === input.botId);
+	return new PermissionsBitField(bits);
+}
+
+/** The Discord REST calls the doctor makes with the bot's own token, over an injected client. */
+export class DiscordApi {
+	readonly #http: Http;
+	readonly #headers: Record<string, string>;
+
+	constructor(http: Http, token: string) {
+		this.#http = http;
+		this.#headers = { Authorization: `Bot ${token}` };
+	}
+
+	get(path: string): Promise<HttpResponse> {
+		return this.#http.get(`${API}${path}`, this.#headers);
+	}
+}

package/src/cli/doctor.test.ts

@@ -0,0 +1,184 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import type { DatabasePort } from "./checks/database.ts";
+import { INVITE_PERMISSIONS } from "./discord-api.ts";
+import { buildChecks, type DoctorInputs, doctor } from "./doctor.ts";
+import { type Check, formatOutcomes, runChecks } from "./report.ts";
+import { start } from "./start.ts";
+import {
+	fakeHttp,
+	fakePorts,
+	healthyDiscord,
+	tempDir,
+	validConfig,
+} from "./testing/fixtures.ts";
+
+const dirs: ReturnType<typeof tempDir>[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) dir.done();
+});
+
+const workingDatabase: DatabasePort = { check: async () => {} };
+const bun = { version: "1.3.10", required: ">=1.3.0" };
+
+function inputs(overrides: Partial<DoctorInputs> = {}): DoctorInputs {
+	const dir = tempDir();
+	dirs.push(dir);
+	return {
+		cwd: dir.path,
+		env: {},
+		bun,
+		ports: fakePorts(),
+		database: workingDatabase,
+		http: fakeHttp({
+			...healthyDiscord(INVITE_PERMISSIONS),
+			"/": { status: 200, body: undefined },
+		}),
+		reachable: false,
+		...overrides,
+	};
+}
+
+describe("doctor", () => {
+	test("lists the checks in the order the spec gives", () => {
+		expect(buildChecks(inputs()).map((check) => check.name)).toEqual([
+			"Bun",
+			"environment",
+			"configuration",
+			"plugins",
+			"PostgreSQL",
+			"Discord token",
+			"Discord guild",
+			"Discord intents",
+			"Discord channel",
+			"model login",
+			"public URL",
+		]);
+	});
+
+	test("passes on a healthy setup", async () => {
+		const report = await doctor(inputs());
+		expect(report.ok).toBe(true);
+		expect(
+			report.outcomes.every(({ result }) => result.status !== "fail"),
+		).toBe(true);
+	});
+
+	test("fails when any check fails, and prints each check as passed or failed with its fix", async () => {
+		const report = await doctor(
+			inputs({
+				ports: fakePorts(validConfig, { login: async () => undefined }),
+			}),
+		);
+		expect(report.ok).toBe(false);
+		const lines = formatOutcomes(report.outcomes);
+		expect(lines.filter((line) => line.startsWith("✓"))).not.toHaveLength(0);
+		const failed = lines.findIndex((line) => line.startsWith("✗ model login"));
+		expect(failed).toBeGreaterThan(-1);
+		expect(lines[failed + 1]).toStartWith("    ");
+		expect(lines[failed + 1]).toContain("API key");
+	});
+
+	test("a missing credential fails the checks that need it and skips what depends on it, changing nothing", async () => {
+		const incomplete = {
+			...validConfig,
+			discord: { ...validConfig.discord, token: "" },
+		};
+		const http = fakeHttp({});
+		const report = await doctor(inputs({ ports: fakePorts(incomplete), http }));
+		const byName = Object.fromEntries(
+			report.outcomes.map(({ name, result }) => [name, result.status]),
+		);
+		expect(byName.configuration).toBe("fail");
+		expect(byName["Discord token"]).toBe("skipped");
+		expect(byName["Discord guild"]).toBe("skipped");
+		expect(byName["Discord channel"]).toBe("skipped");
+		expect(http.requests).toEqual([]);
+		expect(report.ok).toBe(false);
+	});
+
+	test("a check that throws is reported as failed without hiding the ones after it", async () => {
+		const checks: Check[] = [
+			{
+				name: "boom",
+				offline: true,
+				run: async () => {
+					throw new Error("kaput");
+				},
+			},
+			{ name: "fine", offline: true, run: async () => ({ status: "ok" }) },
+		];
+		const outcomes = await runChecks(checks);
+		expect(outcomes.map(({ result }) => result.status)).toEqual(["fail", "ok"]);
+		expect(formatOutcomes(outcomes).join("\n")).toContain("kaput");
+	});
+
+	test("asks the public address to answer only with reachable", async () => {
+		const quiet = inputs();
+		await doctor(quiet);
+		expect((quiet.http as ReturnType<typeof fakeHttp>).requests).not.toContain(
+			"/",
+		);
+		const asking = inputs({ reachable: true });
+		await doctor(asking);
+		expect((asking.http as ReturnType<typeof fakeHttp>).requests).toContain(
+			"/",
+		);
+	});
+});
+
+describe("start", () => {
+	const launched = () => {
+		const seen: DefinedRoundtable[] = [];
+		return {
+			seen,
+			launch: async (defined: DefinedRoundtable) => void seen.push(defined),
+		};
+	};
+
+	test("runs only the checks that need no network, then starts the bot", async () => {
+		const http = fakeHttp({});
+		const { seen, launch } = launched();
+		const report = await start({ ...inputs({ http }), launch });
+		expect(report.started).toBe(true);
+		expect(seen).toHaveLength(1);
+		expect(http.requests).toEqual([]);
+		expect(report.outcomes.map(({ name }) => name)).toEqual([
+			"Bun",
+			"environment",
+			"configuration",
+			"plugins",
+			"model login",
+			"public URL",
+		]);
+	});
+
+	test("a failing check stops it before anything launches, with the message doctor prints", async () => {
+		const failing = inputs({
+			ports: fakePorts(validConfig, { login: async () => undefined }),
+		});
+		const { seen, launch } = launched();
+		const started = await start({ ...failing, launch });
+		expect(started.started).toBe(false);
+		expect(seen).toEqual([]);
+		const fromDoctor = (await doctor(failing)).outcomes.find(
+			({ name }) => name === "model login",
+		);
+		const fromStart = started.outcomes.find(
+			({ name }) => name === "model login",
+		);
+		expect(fromStart).toEqual(fromDoctor as NonNullable<typeof fromDoctor>);
+	});
+
+	test("does not touch the network when the configuration is wrong", async () => {
+		const http = fakeHttp({});
+		const { seen, launch } = launched();
+		const report = await start({
+			...inputs({ ports: fakePorts({}), http }),
+			launch,
+		});
+		expect(report.started).toBe(false);
+		expect(seen).toEqual([]);
+		expect(http.requests).toEqual([]);
+	});
+});

package/src/cli/doctor.ts

@@ -0,0 +1,92 @@
+import { type BunFacts, checkBun } from "./checks/bun.ts";
+import { checkConfiguration, checkPlugins } from "./checks/configuration.ts";
+import { checkDatabase, type DatabasePort } from "./checks/database.ts";
+import {
+	checkChannel,
+	checkGuild,
+	checkIntents,
+	checkToken,
+	Discord,
+} from "./checks/discord.ts";
+import { checkEnvironment } from "./checks/environment.ts";
+import { checkModelLogin } from "./checks/model.ts";
+import { checkPublicUrl } from "./checks/public-url.ts";
+import type { Http } from "./http.ts";
+import { type Ports, Project } from "./project.ts";
+import { type Check, failed, type Outcome, runChecks } from "./report.ts";
+
+export interface DoctorInputs {
+	cwd: string;
+	env: Record<string, string | undefined>;
+	bun: BunFacts;
+	ports: Ports;
+	database: DatabasePort;
+	http: Http;
+	/** Also ask the public address to answer, which is only true while the bot runs. */
+	reachable: boolean;
+}
+
+export interface DoctorReport {
+	ok: boolean;
+	outcomes: Outcome[];
+}
+
+/** Every check, in the order they are shown; `offline` ones need no network and are the ones `start` runs. */
+export function buildChecks(
+	inputs: DoctorInputs,
+	project = new Project(inputs.cwd, inputs.ports),
+): Check[] {
+	const { cwd, env, bun, ports, database, http, reachable } = inputs;
+	const discord = new Discord(project, http);
+	return [
+		{ name: "Bun", offline: true, run: async () => checkBun(bun) },
+		{
+			name: "environment",
+			offline: true,
+			run: async () => checkEnvironment(cwd, env),
+		},
+		{
+			name: "configuration",
+			offline: true,
+			run: () => checkConfiguration(project),
+		},
+		{ name: "plugins", offline: true, run: () => checkPlugins(project) },
+		{
+			name: "PostgreSQL",
+			offline: false,
+			run: () => checkDatabase(project, database),
+		},
+		{ name: "Discord token", offline: false, run: () => checkToken(discord) },
+		{
+			name: "Discord guild",
+			offline: false,
+			run: () => checkGuild(project, discord),
+		},
+		{
+			name: "Discord intents",
+			offline: false,
+			run: () => checkIntents(discord),
+		},
+		{
+			name: "Discord channel",
+			offline: false,
+			run: () => checkChannel(project, discord),
+		},
+		{
+			name: "model login",
+			offline: true,
+			run: () => checkModelLogin(project, ports),
+		},
+		{
+			name: "public URL",
+			offline: true,
+			run: () => checkPublicUrl(project, http, reachable),
+		},
+	];
+}
+
+/** Runs every check and reports each; it changes nothing it looked at. */
+export async function doctor(inputs: DoctorInputs): Promise<DoctorReport> {
+	const outcomes = await runChecks(buildChecks(inputs));
+	return { ok: failed(outcomes).length === 0, outcomes };
+}

package/src/cli/http.ts

@@ -0,0 +1,23 @@
+/** One HTTP answer: its status and its JSON body, undefined when the body is not JSON. */
+export interface HttpResponse {
+	status: number;
+	body: unknown;
+}
+
+/** The one network call the checks make, so tests never touch the network. */
+export interface Http {
+	get(url: string, headers?: Record<string, string>): Promise<HttpResponse>;
+}
+
+const TIMEOUT_MS = 10_000;
+
+export const fetchHttp: Http = {
+	async get(url, headers) {
+		const response = await fetch(url, {
+			headers,
+			signal: AbortSignal.timeout(TIMEOUT_MS),
+		});
+		const body: unknown = await response.json().catch(() => undefined);
+		return { status: response.status, body };
+	},
+};

package/src/cli/init.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BUN_INSTALL_PAGE } from "./checks/bun.ts";
+import { init } from "./init.ts";
+import { tempDir } from "./testing/fixtures.ts";
+
+const dirs: ReturnType<typeof tempDir>[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) dir.done();
+});
+const temp = () => {
+	const dir = tempDir();
+	dirs.push(dir);
+	return dir;
+};
+
+const bun = { version: "1.3.10", required: ">=1.3.0" };
+
+const everything = (dir: string): string[] =>
+	readdirSync(dir, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => join(entry.parentPath, entry.name).slice(dir.length + 1))
+		.sort();
+
+test("init writes the skeleton and the hello plugin, pins the version, and prints three next steps", () => {
+	const dir = temp();
+	const report = init({ cwd: dir.path, dir: "bot", bun, version: "1.2.3" });
+	expect(report.ok).toBe(true);
+	expect(everything(join(dir.path, "bot"))).toEqual(
+		[
+			".env.example",
+			".gitignore",
+			"README.md",
+			"agents.ts",
+			"biome.json",
+			"docker-compose.yml",
+			"package.json",
+			"persona/shared.md",
+			"plugins/hello.test.ts",
+			"plugins/hello.ts",
+			"roundtable.config.ts",
+			"tsconfig.json",
+		].sort(),
+	);
+	expect([...report.created].sort()).toEqual(everything(join(dir.path, "bot")));
+	const manifest = JSON.parse(
+		readFileSync(join(dir.path, "bot/package.json"), "utf8"),
+	) as { name: string; dependencies: Record<string, string> };
+	expect(manifest.name).toBe("bot");
+	expect(manifest.dependencies["pi-roundtable"]).toBe("1.2.3");
+	expect(report.nextSteps).toHaveLength(3);
+	expect(report.nextSteps[0]).toStartWith("cd bot && bun install");
+	expect(report.nextSteps[1]).toContain("roundtable doctor");
+	expect(report.nextSteps[2]).toContain("roundtable start");
+	const hello = readFileSync(join(dir.path, "bot/plugins/hello.ts"), "utf8");
+	expect(hello).toContain('name: "hello"');
+	expect(hello).toContain("hello_greet");
+});
+
+test("init in the current directory needs no cd, and no file keeps a placeholder", () => {
+	const dir = temp();
+	const report = init({ cwd: dir.path, bun, version: "1.2.3" });
+	expect(report.ok).toBe(true);
+	expect(report.nextSteps[0]).toStartWith("bun install");
+	for (const path of everything(dir.path))
+		expect(readFileSync(join(dir.path, path), "utf8")).not.toMatch(
+			/__[A-Z]+__/,
+		);
+});
+
+test("init refuses before writing anything when Bun is missing, naming the install page", () => {
+	const dir = temp();
+	const report = init({
+		cwd: dir.path,
+		bun: { version: undefined, required: ">=1.3.0" },
+		version: "1.2.3",
+	});
+	expect(report.ok).toBe(false);
+	expect(report.problems.join("\n")).toContain(BUN_INSTALL_PAGE);
+	expect(everything(dir.path)).toEqual([]);
+});
+
+test("init refuses when Bun is older than engines.bun, naming both versions and the page", () => {
+	const dir = temp();
+	const report = init({
+		cwd: dir.path,
+		bun: { version: "1.2.9", required: ">=1.3.0" },
+		version: "1.2.3",
+	});
+	expect(report.ok).toBe(false);
+	const text = report.problems.join("\n");
+	expect(text).toContain("1.2.9");
+	expect(text).toContain(">=1.3.0");
+	expect(text).toContain(BUN_INSTALL_PAGE);
+	expect(everything(dir.path)).toEqual([]);
+});
+
+test("init refuses, listing every file that exists, and writes nothing", () => {
+	const dir = temp();
+	dir.write("roundtable.config.ts", "// mine");
+	dir.write("plugins/hello.ts", "// mine");
+	const before = everything(dir.path);
+	const report = init({ cwd: dir.path, bun, version: "1.2.3" });
+	expect(report.ok).toBe(false);
+	const text = report.problems.join("\n");
+	expect(text).toContain("roundtable.config.ts");
+	expect(text).toContain("plugins/hello.ts");
+	expect(text).not.toContain("package.json");
+	expect(everything(dir.path)).toEqual(before);
+	expect(readFileSync(join(dir.path, "roundtable.config.ts"), "utf8")).toBe(
+		"// mine",
+	);
+	expect(existsSync(join(dir.path, "package.json"))).toBe(false);
+});
+
+test("the generated configuration reads credentials from the environment and holds none", () => {
+	const dir = temp();
+	init({ cwd: dir.path, bun, version: "1.2.3" });
+	const config = readFileSync(join(dir.path, "roundtable.config.ts"), "utf8");
+	expect(config).toContain("process.env");
+	for (const key of ["DISCORD_TOKEN", "DATABASE_URL", "OWNER_ID", "MODEL"])
+		expect(config).toContain(`env("${key}")`);
+	expect(config).not.toMatch(/\d{15,}/);
+	expect(config).not.toMatch(/token:\s*"/);
+	expect(readFileSync(join(dir.path, ".gitignore"), "utf8")).toContain(".env");
+});

package/src/cli/init.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { type BunFacts, checkBun } from "./checks/bun.ts";
+import { type Rendered, renderProject, writeRendered } from "./templates.ts";
+
+export interface InitInputs {
+	cwd: string;
+	/** The directory to create the project in, relative to `cwd`; default `cwd` itself. */
+	dir?: string;
+	bun: BunFacts;
+	/** The exact version of pi-roundtable the project pins. */
+	version: string;
+	/** Where the templates are; default the package's own. */
+	templates?: string;
+}
+
+export interface InitReport {
+	ok: boolean;
+	/** Why nothing was written, when `ok` is false. */
+	problems: string[];
+	/** Paths written, relative to the project directory. */
+	created: string[];
+	/** The project directory. */
+	root: string;
+	nextSteps: string[];
+}
+
+/** A package name npm accepts, from a directory's name. */
+function projectName(root: string): string {
+	const name = basename(root)
+		.toLowerCase()
+		.replace(/[^a-z0-9-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return name === "" ? "roundtable-bot" : name;
+}
+
+function nextSteps(cwd: string, root: string): string[] {
+	const where = relative(cwd, root);
+	return [
+		`${where === "" ? "" : `cd ${where} && `}bun install, then copy .env.example to .env and fill in the credentials it lists`,
+		"bunx roundtable doctor: it lists what is still missing and how to fix it",
+		"bunx roundtable start",
+	];
+}
+
+/**
+ * Creates a project. Every refusal is decided before the first write: Bun missing or too old,
+ * or any file it would create already there.
+ */
+export function init(inputs: InitInputs): InitReport {
+	const root = resolve(inputs.cwd, inputs.dir ?? ".");
+	const refused = (problems: string[]): InitReport => ({
+		ok: false,
+		problems,
+		created: [],
+		root,
+		nextSteps: [],
+	});
+	const bun = checkBun(inputs.bun);
+	if (bun.status === "fail") return refused([bun.problem, bun.fix]);
+	const files: Rendered[] = renderProject(
+		{ project: projectName(root), version: inputs.version },
+		inputs.templates,
+	);
+	const existing = files
+		.map((file) => file.path)
+		.filter((path) => existsSync(join(root, path)));
+	if (existing.length > 0)
+		return refused([
+			`${existing.length === 1 ? "A file" : "Files"} init would create already exist in ${root}:`,
+			...existing.map((path) => `  ${path}`),
+			"Remove them or run init in an empty directory; nothing was written.",
+		]);
+	writeRendered(root, files);
+	return {
+		ok: true,
+		problems: [],
+		created: files.map((file) => file.path),
+		root,
+		nextSteps: nextSteps(inputs.cwd, root),
+	};
+}

package/src/cli/main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { processEnvironment, runCli } from "./cli.ts";
+
+// pi-lens-ignore: no-unknown-parameters
+runCli(process.argv.slice(2), processEnvironment()).then(
+	(code) => {
+		process.exitCode = code;
+	},
+	(error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	},
+);