pi-roundtable 0.1.0

package/src/cli/checks/public-url.ts

@@ -0,0 +1,40 @@
+import type { Http } from "../http.ts";
+import type { Project } from "../project.ts";
+import { fail, ok, type Result, skipped } from "../report.ts";
+
+/**
+ * The public address is a well-formed http(s) URL; with `reachable`, it also answers, which is
+ * only true while the bot runs, so it is opt-in.
+ */
+export async function checkPublicUrl(
+	project: Project,
+	http: Http,
+	reachable: boolean,
+): Promise<Result> {
+	const value = await project.text("http", "publicUrl");
+	if (!value) return skipped("http.publicUrl has no value");
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		return fail(
+			`${JSON.stringify(value)} is not a URL.`,
+			"Write the full address, such as https://bot.example.com, in PUBLIC_URL in .env.",
+		);
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:")
+		return fail(
+			`${value} does not start with http:// or https://.`,
+			"Discord fetches the agents' avatars from this address; use an http(s) URL.",
+		);
+	if (!reachable) return ok(`${value} is well formed`);
+	try {
+		const { status } = await http.get(value);
+		return ok(`${value} answered ${status}`);
+	} catch (error) {
+		return fail(
+			`${value} did not answer: ${error instanceof Error ? error.message : String(error)}`,
+			"Start the bot (`roundtable start`) and check the tunnel or proxy that publishes this address.",
+		);
+	}
+}

package/src/cli/cli.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type CliEnvironment, readPackage, runCli } from "./cli.ts";
+import { fakePorts, tempDir, validConfig } from "./testing/fixtures.ts";
+
+const dirs: ReturnType<typeof tempDir>[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) dir.done();
+});
+
+function cli(overrides: Partial<CliEnvironment> = {}) {
+	const dir = tempDir();
+	dirs.push(dir);
+	const out: string[] = [];
+	const err: string[] = [];
+	const launched: unknown[] = [];
+	const io: CliEnvironment = {
+		cwd: dir.path,
+		env: {},
+		bun: () => ({ version: "1.3.10", required: ">=1.3.0" }),
+		version: () => "1.2.3",
+		ports: fakePorts(),
+		launch: async (defined) => void launched.push(defined),
+		out: (line) => out.push(line),
+		err: (line) => err.push(line),
+		...overrides,
+	};
+	return { io, out, err, launched, dir };
+}
+
+test("no command prints the usage and exits non-zero; help and --version exit zero", async () => {
+	const none = cli();
+	expect(await runCli([], none.io)).toBe(1);
+	expect(none.out.join("\n")).toContain("roundtable init");
+	const help = cli();
+	expect(await runCli(["--help"], help.io)).toBe(0);
+	const version = cli();
+	expect(await runCli(["--version"], version.io)).toBe(0);
+	expect(version.out).toEqual(["1.2.3"]);
+});
+
+test("an unknown command or a wrong argument list prints the problem and exits non-zero", async () => {
+	for (const argv of [
+		["frobnicate"],
+		["add"],
+		["add", "plugin"],
+		["add", "thing", "x"],
+		["add", "plugin", "a", "b"],
+		["init", "a", "b"],
+		["doctor", "extra"],
+		["start", "--reachable"],
+	]) {
+		const run = cli();
+		expect(await runCli(argv, run.io)).toBe(1);
+		expect(run.err.length).toBeGreaterThan(0);
+	}
+});
+
+test("init prints what it created and the three next steps, and exits zero; a second run refuses", async () => {
+	const run = cli();
+	expect(await runCli(["init", "bot"], run.io)).toBe(0);
+	const text = run.out.join("\n");
+	expect(text).toContain("roundtable.config.ts");
+	expect(text).toContain("1. cd bot && bun install");
+	expect(text).toContain("3. bunx roundtable start");
+	expect(existsSync(join(run.dir.path, "bot/plugins/hello.ts"))).toBe(true);
+	const again = await runCli(["init", "bot"], run.io);
+	expect(again).toBe(1);
+	expect(run.err.join("\n")).toContain("already exist");
+});
+
+test("init on an old Bun refuses with the install page and creates nothing", async () => {
+	const run = cli({ bun: () => ({ version: "1.0.0", required: ">=1.3.0" }) });
+	expect(await runCli(["init"], run.io)).toBe(1);
+	expect(run.err.join("\n")).toContain("https://bun.sh/docs/installation");
+	expect(existsSync(join(run.dir.path, "package.json"))).toBe(false);
+});
+
+test("add plugin exits zero after init and non-zero on a bad name", async () => {
+	const run = cli();
+	await runCli(["init"], run.io);
+	expect(await runCli(["add", "plugin", "notes"], run.io)).toBe(0);
+	expect(
+		readFileSync(join(run.dir.path, "roundtable.config.ts"), "utf8"),
+	).toContain("plugins: [hello, notes]");
+	expect(await runCli(["add", "plugin", "Bad_Name"], run.io)).toBe(1);
+});
+
+test("doctor exits non-zero when a check fails and zero when none does", async () => {
+	const failing = cli({
+		ports: fakePorts(validConfig, { login: async () => undefined }),
+	});
+	expect(await runCli(["doctor"], failing.io)).toBe(1);
+	expect(failing.out.join("\n")).toContain("✗ model login");
+});
+
+test("start exits non-zero without launching when an offline check fails, and launches otherwise", async () => {
+	const failing = cli({ ports: fakePorts({}) });
+	expect(await runCli(["start"], failing.io)).toBe(1);
+	expect(failing.launched).toEqual([]);
+	expect(failing.err.join("\n")).toContain("✗ configuration");
+	const working = cli();
+	expect(await runCli(["start"], working.io)).toBe(0);
+	expect(working.launched).toHaveLength(1);
+});
+
+test("readPackage reads the version and Bun range, and refuses a package.json without them", () => {
+	const dir = tempDir();
+	dirs.push(dir);
+	dir.write(
+		"package.json",
+		JSON.stringify({ version: "0.1.0", engines: { bun: ">=1.3.0" } }),
+	);
+	expect(readPackage(dir.path)).toEqual({ version: "0.1.0", bun: ">=1.3.0" });
+	dir.write("package.json", JSON.stringify({ name: "private" }));
+	expect(() => readPackage(dir.path)).toThrow(
+		"installed pi-roundtable package",
+	);
+	dir.write("package.json", "{ nope");
+	expect(() => readPackage(dir.path)).toThrow("not valid JSON");
+});

package/src/cli/cli.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import { Roundtable } from "../core/host.ts";
+import { addPlugin } from "./add-plugin.ts";
+import type { BunFacts } from "./checks/bun.ts";
+import { postgres } from "./checks/database.ts";
+import { doctor } from "./doctor.ts";
+import { fetchHttp } from "./http.ts";
+import { init } from "./init.ts";
+import { loadConfigFile, type Ports } from "./project.ts";
+import { formatOutcomes } from "./report.ts";
+import { assemble, providerLogin } from "./runtime.ts";
+import { start } from "./start.ts";
+
+/** What the command line reads from its surroundings; tests replace every part. */
+export interface CliEnvironment {
+	cwd: string;
+	env: Record<string, string | undefined>;
+	bun: () => BunFacts;
+	version: () => string;
+	ports: Ports;
+	launch(defined: DefinedRoundtable): Promise<void>;
+	out(line: string): void;
+	err(line: string): void;
+}
+
+const USAGE = `roundtable: a Discord agent server on Pi
+
+  roundtable init [dir]         create a project (default: the current directory)
+  roundtable doctor [--reachable]  check the setup and say how to fix what is wrong
+  roundtable start              run the checks that need no network, then the bot
+  roundtable add plugin <name>  add plugins/<name>.ts and its test, and list it in the config
+`;
+
+/** The package's own version and the Bun range it needs, from the package.json beside the source. */
+export function readPackage(dir = join(import.meta.dir, "../..")): {
+	version: string;
+	bun: string;
+} {
+	const path = join(dir, "package.json");
+	let manifest: { version?: string; engines?: { bun?: string } } = {};
+	if (existsSync(path)) {
+		try {
+			manifest = JSON.parse(readFileSync(path, "utf8"));
+		} catch (error) {
+			throw new Error(`${path} is not valid JSON: ${String(error)}`, {
+				cause: error,
+			});
+		}
+	}
+	if (!manifest.version || !manifest.engines?.bun)
+		throw new Error(
+			`${path} has no version and engines.bun; the roundtable command runs from an installed pi-roundtable package.`,
+		);
+	return { version: manifest.version, bun: manifest.engines.bun };
+}
+
+/** The real surroundings of the process. */
+export function processEnvironment(): CliEnvironment {
+	return {
+		cwd: process.cwd(),
+		env: process.env,
+		bun: () => ({
+			version: typeof Bun === "undefined" ? undefined : Bun.version,
+			required: readPackage().bun,
+		}),
+		version: () => readPackage().version,
+		ports: {
+			loadConfig: loadConfigFile,
+			define: assemble,
+			login: providerLogin,
+		},
+		launch: async (defined) => {
+			const roundtable = new Roundtable(defined.options, defined.plugins);
+			roundtable.listen();
+			await roundtable.run();
+		},
+		out: (line) => console.log(line),
+		err: (line) => console.error(line),
+	};
+}
+
+/** Parses the arguments, runs one command, prints its report, and returns the exit code. */
+export async function runCli(
+	argv: readonly string[],
+	io: CliEnvironment,
+): Promise<number> {
+	const [command, ...rest] = argv;
+	if (command === undefined || command === "help" || command === "--help") {
+		io.out(USAGE);
+		return command === undefined ? 1 : 0;
+	}
+	if (command === "--version") {
+		io.out(io.version());
+		return 0;
+	}
+	if (command === "init") {
+		const [dir, ...extra] = rest;
+		if (extra.length > 0) return usage(io, "init takes at most one directory");
+		const report = init({
+			cwd: io.cwd,
+			...(dir === undefined ? {} : { dir }),
+			bun: io.bun(),
+			version: io.version(),
+		});
+		if (!report.ok) {
+			for (const line of report.problems) io.err(line);
+			return 1;
+		}
+		io.out(`Created ${report.created.length} files in ${report.root}:`);
+		for (const path of report.created) io.out(`  ${path}`);
+		io.out("\nNext:");
+		for (const [index, step] of report.nextSteps.entries())
+			io.out(`  ${index + 1}. ${step}`);
+		return 0;
+	}
+	if (command === "add") {
+		const [what, name, ...extra] = rest;
+		if (what !== "plugin" || name === undefined || extra.length > 0)
+			return usage(io, "usage: roundtable add plugin <name>");
+		const report = addPlugin({ cwd: io.cwd, name });
+		if (!report.ok) {
+			for (const line of report.problems) io.err(line);
+			return 1;
+		}
+		io.out(`Added the plugin ${name}:`);
+		for (const path of report.changed) io.out(`  ${path}`);
+		return 0;
+	}
+	if (command === "doctor" || command === "start") {
+		const flags = rest.filter((arg) => arg.startsWith("-"));
+		const reachable = flags.includes("--reachable");
+		if (
+			rest.length > 0 &&
+			!(rest.length === 1 && reachable && command === "doctor")
+		)
+			return usage(io, `${command} takes no arguments`);
+		const inputs = {
+			cwd: resolve(io.cwd),
+			env: io.env,
+			bun: io.bun(),
+			ports: io.ports,
+			database: postgres,
+			http: fetchHttp,
+		};
+		if (command === "doctor") {
+			const report = await doctor({ ...inputs, reachable });
+			for (const line of formatOutcomes(report.outcomes)) io.out(line);
+			return report.ok ? 0 : 1;
+		}
+		const report = await start({ ...inputs, launch: io.launch });
+		if (!report.started) {
+			for (const line of formatOutcomes(report.outcomes)) io.err(line);
+			return 1;
+		}
+		return 0;
+	}
+	return usage(io, `unknown command ${JSON.stringify(command)}`);
+}
+
+function usage(io: CliEnvironment, message: string): number {
+	io.err(message);
+	io.err(USAGE);
+	return 1;
+}

package/src/cli/config-edit.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { addPluginToConfig, ConfigEditError } from "./config-edit.ts";
+
+const notes = { name: "my-notes", ident: "myNotes" };
+const edit = (source: string) => addPluginToConfig(source, notes);
+const refusal = (source: string): string => {
+	try {
+		edit(source);
+	} catch (error) {
+		if (error instanceof ConfigEditError) return error.message;
+		throw error;
+	}
+	return "";
+};
+
+describe("addPluginToConfig", () => {
+	test("adds the import after the imports and the entry after the last one", () => {
+		const source = `import type { Config } from "node:fs";
+import { hello } from "./plugins/hello.ts";
+
+export default {
+	name: "Bot",
+	plugins: [hello],
+} satisfies Config;
+`;
+		expect(edit(source)).toBe(`import type { Config } from "node:fs";
+import { hello } from "./plugins/hello.ts";
+import { myNotes } from "./plugins/my-notes.ts";
+
+export default {
+	name: "Bot",
+	plugins: [hello, myNotes],
+} satisfies Config;
+`);
+	});
+
+	test("puts the import in sorted place among the relative imports", () => {
+		const source = `import { agents } from "./agents.ts";
+import { hello } from "./plugins/hello.ts";
+import { zed } from "./plugins/zed.ts";
+
+export default { plugins: [hello, zed] };
+`;
+		const lines = edit(source).split("\n");
+		expect(lines.slice(0, 4)).toEqual([
+			'import { agents } from "./agents.ts";',
+			'import { hello } from "./plugins/hello.ts";',
+			'import { myNotes } from "./plugins/my-notes.ts";',
+			'import { zed } from "./plugins/zed.ts";',
+		]);
+	});
+
+	test("keeps a multi-line list's layout, with or without a trailing comma", () => {
+		const bare = `import { a } from "./plugins/a.ts";
+export default {
+	plugins: [
+		a,
+	],
+};
+`;
+		expect(edit(bare)).toContain("\t\ta,\n\t\tmyNotes,\n\t],");
+		const noComma = bare.replace("a,\n\t]", "a\n\t]");
+		expect(edit(noComma)).toContain("\t\ta,\n\t\tmyNotes\n\t],");
+	});
+
+	test("fills an empty list and adds the import to a file without imports", () => {
+		const edited = edit("export default { plugins: [] };\n");
+		expect(edited).toBe(
+			'import { myNotes } from "./plugins/my-notes.ts";\n\nexport default { plugins: [myNotes] };\n',
+		);
+	});
+
+	test("finds the list under as, satisfies, parentheses, and a named constant", () => {
+		for (const source of [
+			"export default { plugins: [a] } as const;",
+			"export default ({ plugins: [a] });",
+			"export default { plugins: [a] as Plugin[] };",
+			"const config = { plugins: [a] } satisfies X;\nexport default config;",
+			'export default { "plugins": [a] };',
+		])
+			expect(edit(source)).toContain("a, myNotes]");
+	});
+
+	test("leaves comments and every other byte as they were", () => {
+		const source = `// the bot
+import { a } from "./plugins/a.ts";
+
+export default {
+	// who
+	owner: { id: "1" },
+	plugins: [a /* first */], // done
+};
+`;
+		const edited = edit(source);
+		expect(edited).toContain("// the bot");
+		expect(edited).toContain("// who");
+		// The entry goes right after the last element, before anything that follows it on the line.
+		expect(edited).toContain("plugins: [a, myNotes /* first */], // done");
+	});
+
+	test("refuses a default export with no plugin list, naming the file and what to add", () => {
+		for (const source of [
+			"export default { name: 'x' };",
+			"export default { plugins: somePlugins };",
+			"export default makeConfig();",
+			"export const config = { plugins: [] };",
+			"export default { other: { plugins: [] } };",
+		]) {
+			const text = refusal(source);
+			expect(text).toContain("roundtable.config.ts");
+			expect(text).toContain("cannot find the plugin list");
+			expect(text).toContain('import { myNotes } from "./plugins/my-notes.ts"');
+		}
+	});
+
+	test("refuses a name the file already uses, and a plugin already listed", () => {
+		expect(
+			refusal(
+				'import { myNotes } from "./plugins/my-notes.ts";\nexport default { plugins: [myNotes] };',
+			),
+		).toContain("myNotes is already used");
+		expect(
+			refusal("const myNotes = 1;\nexport default { plugins: [] };"),
+		).toContain("already used");
+	});
+
+	test("refuses a file that does not parse and says so", () => {
+		expect(refusal("export default { plugins: [ ")).toContain("does not parse");
+	});
+});

package/src/cli/config-edit.ts

@@ -0,0 +1,199 @@
+import { parse } from "@babel/parser";
+
+/** The parts of a syntax node this edit reads; the parser's own types are not needed beyond these. */
+interface Node {
+	type: string;
+	start: number;
+	end: number;
+	[key: string]: unknown;
+}
+
+/** A configuration this edit cannot change, and why; the message says what to do by hand. */
+export class ConfigEditError extends Error {
+	override name = "ConfigEditError";
+}
+
+const WRAPPERS = new Set([
+	"TSSatisfiesExpression",
+	"TSAsExpression",
+	"TSNonNullExpression",
+	"ParenthesizedExpression",
+]);
+
+const child = (node: Node, key: string): Node | undefined => {
+	const value = node[key];
+	return typeof value === "object" && value !== null
+		? (value as Node)
+		: undefined;
+};
+
+/** The expression under `satisfies`, `as`, `!`, and parentheses. */
+function unwrap(node: Node | undefined): Node | undefined {
+	let current = node;
+	while (current && WRAPPERS.has(current.type))
+		current = child(current, "expression");
+	return current;
+}
+
+function parseModule(source: string, file: string): Node[] {
+	try {
+		// SAFETY: every node the parser builds has a type, start, and end, which is all Node states.
+		return parse(source, {
+			sourceType: "module",
+			plugins: ["typescript"],
+		}).program.body as unknown as Node[];
+	} catch (error) {
+		throw new ConfigEditError(
+			`${file} does not parse (${error instanceof Error ? error.message : String(error)}). Fix it, or add the plugin to its list by hand.`,
+		);
+	}
+}
+
+const nameOf = (node: Node | undefined): string | undefined => {
+	if (node?.type === "Identifier") return node.name as string;
+	if (node?.type === "StringLiteral") return node.value as string;
+	return undefined;
+};
+
+/** Every name the module already binds at its top level, so an import cannot shadow one. */
+function boundNames(body: readonly Node[]): Set<string> {
+	const names = new Set<string>();
+	for (const statement of body) {
+		const declaration =
+			statement.type === "ExportNamedDeclaration"
+				? child(statement, "declaration")
+				: statement;
+		if (statement.type === "ImportDeclaration")
+			for (const specifier of statement.specifiers as Node[]) {
+				const local = nameOf(child(specifier, "local"));
+				if (local) names.add(local);
+			}
+		if (declaration?.type === "VariableDeclaration")
+			for (const declarator of declaration.declarations as Node[]) {
+				const id = nameOf(child(declarator, "id"));
+				if (id) names.add(id);
+			}
+		const id = nameOf(declaration ? child(declaration, "id") : undefined);
+		if (id) names.add(id);
+	}
+	return names;
+}
+
+/** The object the config exports: the default export itself, or the top-level constant it names. */
+function exportedObject(body: readonly Node[]): Node | undefined {
+	const exported = body.find(
+		(node) => node.type === "ExportDefaultDeclaration",
+	);
+	const value = unwrap(exported ? child(exported, "declaration") : undefined);
+	if (value?.type === "ObjectExpression") return value;
+	if (value?.type !== "Identifier") return undefined;
+	for (const statement of body) {
+		const declaration =
+			statement.type === "ExportNamedDeclaration"
+				? child(statement, "declaration")
+				: statement;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations as Node[]) {
+			if (nameOf(child(declarator, "id")) !== value.name) continue;
+			const init = unwrap(child(declarator, "init"));
+			if (init?.type === "ObjectExpression") return init;
+		}
+	}
+	return undefined;
+}
+
+function pluginList(object: Node): Node | undefined {
+	for (const property of object.properties as Node[]) {
+		if (property.type !== "ObjectProperty") continue;
+		if (nameOf(child(property, "key")) !== "plugins") continue;
+		const list = unwrap(child(property, "value"));
+		if (list?.type === "ArrayExpression") return list;
+	}
+	return undefined;
+}
+
+interface Insertion {
+	at: number;
+	text: string;
+}
+
+/** The text to add so `ident` joins the list, in the list's own layout. */
+function listInsertion(source: string, list: Node, ident: string): Insertion {
+	const elements = (list.elements as (Node | null)[]).filter(
+		(element): element is Node => element !== null,
+	);
+	const last = elements.at(-1);
+	if (!last) return { at: list.start + 1, text: ident };
+	const between = source.slice(last.end, list.end - 1);
+	const comma = between.search(/[^\s]/);
+	const trailing = between[comma] === "," ? last.end + comma + 1 : undefined;
+	const multiline = source.slice(list.start, last.start).includes("\n");
+	const lineStart = source.lastIndexOf("\n", last.start) + 1;
+	const indent = /^[ \t]*/.exec(source.slice(lineStart, last.start))?.[0] ?? "";
+	if (trailing !== undefined)
+		return {
+			at: trailing,
+			text: multiline ? `\n${indent}${ident},` : ` ${ident},`,
+		};
+	return {
+		at: last.end,
+		text: multiline ? `,\n${indent}${ident}` : `, ${ident}`,
+	};
+}
+
+/** Where the new import goes: before the first later-sorting relative import, else after the last import. */
+function importInsertion(
+	body: readonly Node[],
+	specifier: string,
+	line: string,
+): Insertion {
+	const imports = body.filter((node) => node.type === "ImportDeclaration");
+	const later = imports.find((node) => {
+		const from = (child(node, "source")?.value ?? "") as string;
+		return from.startsWith(".") && from > specifier;
+	});
+	if (later) return { at: later.start, text: `${line}\n` };
+	const last = imports.at(-1);
+	return last
+		? { at: last.end, text: `\n${line}` }
+		: { at: 0, text: `${line}\n\n` };
+}
+
+/**
+ * Adds the plugin's import line and lists it in the `plugins` array of the default export, in the
+ * file's own layout. It refuses, changing nothing, a file that does not parse, a default export
+ * with no `plugins` list it can find, and a name already bound.
+ */
+export function addPluginToConfig(
+	source: string,
+	plugin: { name: string; ident: string },
+	file = "roundtable.config.ts",
+): string {
+	const body = parseModule(source, file);
+	const object = exportedObject(body);
+	const list = object ? pluginList(object) : undefined;
+	if (!list)
+		throw new ConfigEditError(
+			`${file}: cannot find the plugin list. Expected \`export default { ..., plugins: [...] }\`; add \`import { ${plugin.ident} } from "./plugins/${plugin.name}.ts"\` and list ${plugin.ident} in plugins by hand.`,
+		);
+	const specifier = `./plugins/${plugin.name}.ts`;
+	if (boundNames(body).has(plugin.ident))
+		throw new ConfigEditError(
+			`${file}: the name ${plugin.ident} is already used. Import the plugin by hand under another name.`,
+		);
+	const edits = [
+		listInsertion(source, list, plugin.ident),
+		importInsertion(
+			body,
+			specifier,
+			// JSON.stringify quotes the specifier; the export script reads import lines in source text, so none may hold a placeholder.
+			`import { ${plugin.ident} } from ${JSON.stringify(specifier)};`,
+		),
+	].sort((a, b) => b.at - a.at);
+	let edited = source;
+	for (const edit of edits)
+		edited = edited.slice(0, edit.at) + edit.text + edited.slice(edit.at);
+	// A result that does not parse is a bug here; never write it.
+	parseModule(edited, file);
+	return edited;
+}