pi-roundtable 0.1.0

package/src/cli/project.ts

@@ -0,0 +1,123 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+	type ResolvedConfig,
+	type RoundtableConfig,
+	resolveConfig,
+} from "../core/config/config.ts";
+import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import { fail, type Result } from "./report.ts";
+
+export const CONFIG_FILE = "roundtable.config.ts";
+
+/** What the command line reaches outside itself, so each check can be run against a fake. */
+export interface Ports {
+	/** The value `roundtable.config.ts` exports by default. */
+	loadConfig(cwd: string): Promise<unknown>;
+	/** The bot's options and plugin list, assembled from a valid configuration. */
+	define(
+		config: RoundtableConfig,
+		agentDir: string,
+	): Promise<DefinedRoundtable>;
+	/** Where the login for `provider` in `agentDir` comes from, or undefined when there is none. */
+	login(agentDir: string, provider: string): Promise<string | undefined>;
+}
+
+/** Loads the project's configuration file with Bun, which reads `.env` on its own. */
+export async function loadConfigFile(cwd: string): Promise<unknown> {
+	const path = join(cwd, CONFIG_FILE);
+	if (!existsSync(path))
+		throw new Error(
+			`${CONFIG_FILE} is not in ${cwd}. Run this in the project directory, or create a project with \`roundtable init\`.`,
+		);
+	const module = (await import(pathToFileURL(path).href)) as {
+		default?: unknown;
+	};
+	if (module.default === undefined)
+		throw new Error(
+			`${CONFIG_FILE} has no default export. Write \`export default { ... } satisfies RoundtableConfig\`.`,
+		);
+	return module.default;
+}
+
+type Loaded<T> = { ok: true; value: T } | { ok: false; failure: Result };
+
+export interface Assembled {
+	config: ResolvedConfig;
+	defined: DefinedRoundtable;
+}
+
+const message = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);
+
+/**
+ * The project's configuration, loaded and resolved at most once and shared by every check, so a
+ * mistake in it is reported by the configuration check and the checks that need it say so
+ * rather than repeating it.
+ */
+export class Project {
+	readonly #cwd: string;
+	readonly #ports: Ports;
+	#raw: Promise<Loaded<unknown>> | undefined;
+	#assembled: Promise<Loaded<Assembled>> | undefined;
+
+	constructor(cwd: string, ports: Ports) {
+		this.#cwd = cwd;
+		this.#ports = ports;
+	}
+
+	/** The exported value as written, before the schema looks at it. */
+	raw(): Promise<Loaded<unknown>> {
+		this.#raw ??= this.#ports.loadConfig(this.#cwd).then(
+			(value): Loaded<unknown> => ({ ok: true, value }),
+			(error: unknown): Loaded<unknown> => ({
+				ok: false,
+				failure: fail(
+					`${CONFIG_FILE} could not be loaded: ${message(error)}`,
+					`Fix the error in ${CONFIG_FILE}.`,
+				),
+			}),
+		);
+		return this.#raw;
+	}
+
+	/** A string at `path` in the configuration as written, even when other keys are wrong. */
+	async text(...path: string[]): Promise<string | undefined> {
+		const raw = await this.raw();
+		if (!raw.ok) return undefined;
+		let value: unknown = raw.value;
+		for (const key of path) {
+			if (typeof value !== "object" || value === null) return undefined;
+			value = (value as Record<string, unknown>)[key];
+		}
+		return typeof value === "string" && value.trim() !== "" ? value : undefined;
+	}
+
+	/** The configuration checked against its schema and assembled, or the failure that says why not. */
+	assembled(): Promise<Loaded<Assembled>> {
+		this.#assembled ??= this.#assemble();
+		return this.#assembled;
+	}
+
+	async #assemble(): Promise<Loaded<Assembled>> {
+		const raw = await this.raw();
+		if (!raw.ok) return raw;
+		try {
+			const config = resolveConfig(raw.value);
+			const defined = await this.#ports.define(
+				raw.value as RoundtableConfig,
+				config.agentDir,
+			);
+			return { ok: true, value: { config, defined } };
+		} catch (error) {
+			return {
+				ok: false,
+				failure: fail(
+					message(error),
+					`Fix the key in ${CONFIG_FILE}; a value it reads from .env is set there (see .env.example).`,
+				),
+			};
+		}
+	}
+}

package/src/cli/report.ts

@@ -0,0 +1,68 @@
+/** How one check ended: passed, failed with what to do, or not run because it needs something an earlier check reports. */
+export type Result =
+	| { status: "ok"; detail?: string }
+	| { status: "fail"; problem: string; fix: string }
+	| { status: "skipped"; reason: string };
+
+/** One thing `doctor` looks at. `offline` checks need no network, so `start` runs them too. */
+export interface Check {
+	name: string;
+	offline: boolean;
+	run(): Promise<Result>;
+}
+
+export interface Outcome {
+	name: string;
+	result: Result;
+}
+
+export const ok = (detail?: string): Result =>
+	detail === undefined ? { status: "ok" } : { status: "ok", detail };
+export const fail = (problem: string, fix: string): Result => ({
+	status: "fail",
+	problem,
+	fix,
+});
+export const skipped = (reason: string): Result => ({
+	status: "skipped",
+	reason,
+});
+
+const errorText = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);
+
+/** Runs the checks in order. A check that throws fails with its message, so a bug in one never hides the rest. */
+export async function runChecks(checks: readonly Check[]): Promise<Outcome[]> {
+	const outcomes: Outcome[] = [];
+	for (const check of checks) {
+		try {
+			outcomes.push({ name: check.name, result: await check.run() });
+		} catch (error) {
+			outcomes.push({
+				name: check.name,
+				result: fail(
+					`the check itself failed: ${errorText(error)}`,
+					"Report this as a bug in roundtable doctor.",
+				),
+			});
+		}
+	}
+	return outcomes;
+}
+
+export const failed = (outcomes: readonly Outcome[]): Outcome[] =>
+	outcomes.filter(({ result }) => result.status === "fail");
+
+/** One line per check, and for a failure its problem and fix underneath. */
+export function formatOutcomes(outcomes: readonly Outcome[]): string[] {
+	return outcomes.flatMap(({ name, result }) => {
+		if (result.status === "ok")
+			return [`✓ ${name}${result.detail ? `: ${result.detail}` : ""}`];
+		if (result.status === "skipped")
+			return [`- ${name}: skipped, ${result.reason}`];
+		return [
+			`✗ ${name}: ${result.problem}`,
+			...result.fix.split("\n").map((line) => `    ${line}`),
+		];
+	});
+}

package/src/cli/roundtable.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// The bin npm links. It runs under Node only to find Bun: with Bun it hands over, without it
+// it says where to get it, since a `bun` shebang would fail with an error nobody can read.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const main = fileURLToPath(new URL("./main.ts", import.meta.url));
+
+if (typeof Bun !== "undefined") {
+	await import("./main.ts");
+} else {
+	const run = spawnSync("bun", [main, ...process.argv.slice(2)], {
+		stdio: "inherit",
+	});
+	if (run.error?.code === "ENOENT") {
+		console.error(
+			"Bun is not installed. pi-roundtable runs on Bun: install it from https://bun.sh/docs/installation and run this command again.",
+		);
+		process.exit(1);
+	}
+	process.exit(run.status ?? 1);
+}

package/src/cli/runtime.ts

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Credential, CredentialStore } from "@earendil-works/pi-ai";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import { defineRoundtable } from "../core/define-roundtable.ts";
+
+/** A credential store that holds nothing and refuses writes, so looking never creates `auth.json`. */
+const emptyCredentials: CredentialStore = {
+	read: async () => undefined,
+	list: async () => [],
+	modify: async (): Promise<Credential | undefined> => {
+		throw new Error("the doctor does not change logins");
+	},
+	delete: async () => {
+		throw new Error("the doctor does not change logins");
+	},
+};
+
+/**
+ * The model login as the bot would open it, without creating the agent directory or
+ * `auth.json` when there is none yet.
+ */
+export async function openModelRuntime(
+	agentDir: string,
+): Promise<ModelRuntime> {
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	const authPath = join(agentDir, "auth.json");
+	return await ModelRuntime.create(
+		existsSync(authPath)
+			? { authPath, refreshOnCreate: false }
+			: { credentials: emptyCredentials, refreshOnCreate: false },
+	);
+}
+
+/** Where the configured provider's login comes from (a key variable or the stored login), undefined when there is none. */
+export async function providerLogin(
+	agentDir: string,
+	provider: string,
+): Promise<string | undefined> {
+	const check = await (await openModelRuntime(agentDir)).checkAuth(provider);
+	return check ? (check.source ?? check.type) : undefined;
+}
+
+/** The configuration assembled as the bot will run it, over a login that is only read. */
+export async function assemble(
+	config: Parameters<typeof defineRoundtable>[0],
+	agentDir: string,
+): Promise<DefinedRoundtable> {
+	return await defineRoundtable(config, {
+		modelRuntime: await openModelRuntime(agentDir),
+	});
+}

package/src/cli/size.test.ts

@@ -0,0 +1,9 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { oversizedFiles } from "../core/testing/file-size.ts";
+
+test("no file of the command line is over the size limit", () => {
+	expect(
+		oversizedFiles(resolve(import.meta.dir, "../.."), ["src/cli"]),
+	).toEqual([]);
+});

package/src/cli/start.ts

@@ -0,0 +1,33 @@
+import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import { buildChecks, type DoctorInputs } from "./doctor.ts";
+import { Project } from "./project.ts";
+import { failed, type Outcome, runChecks } from "./report.ts";
+
+export interface StartInputs extends Omit<DoctorInputs, "reachable"> {
+	/** Runs the bot; by default the host with its signal handlers. Tests pass a fake. */
+	launch(defined: DefinedRoundtable): Promise<void>;
+}
+
+export interface StartReport {
+	/** Whether the bot was launched. */
+	started: boolean;
+	outcomes: Outcome[];
+}
+
+/**
+ * Runs the checks that need no network, then starts the bot. A failing check stops it before
+ * anything reaches Discord, with the message `doctor` prints for it; what needs the network
+ * (PostgreSQL, Discord) fails the boot itself, before Discord connects, when it is wrong.
+ */
+export async function start(inputs: StartInputs): Promise<StartReport> {
+	const project = new Project(inputs.cwd, inputs.ports);
+	const offline = buildChecks({ ...inputs, reachable: false }, project).filter(
+		(check) => check.offline,
+	);
+	const outcomes = await runChecks(offline);
+	if (failed(outcomes).length > 0) return { started: false, outcomes };
+	const assembled = await project.assembled();
+	if (!assembled.ok) return { started: false, outcomes };
+	await inputs.launch(assembled.value.defined);
+	return { started: true, outcomes };
+}

package/src/cli/templates.test.ts

@@ -0,0 +1,129 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { addPlugin } from "./add-plugin.ts";
+import { init } from "./init.ts";
+import { tempDir } from "./testing/fixtures.ts";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const TSC = join(ROOT, "node_modules/.bin/tsc");
+const BIOME = join(ROOT, "node_modules/.bin/biome");
+
+function run(cwd: string, cmd: string[]): { ok: boolean; output: string } {
+	const result = Bun.spawnSync(cmd, {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+		env: { ...process.env, CI: "" },
+	});
+	return {
+		ok: result.exitCode === 0,
+		output: `${result.stdout.toString()}${result.stderr.toString()}`,
+	};
+}
+
+/**
+ * The generated project with `pi-roundtable`, `typebox`, and the types linked from this
+ * checkout, so it typechecks and tests against the source under test without the network.
+ */
+function link(project: string): void {
+	const modules = join(project, "node_modules");
+	mkdirSync(join(modules, "pi-roundtable"), { recursive: true });
+	mkdirSync(join(modules, "@types"), { recursive: true });
+	writeFileSync(
+		join(modules, "pi-roundtable/package.json"),
+		JSON.stringify({
+			name: "pi-roundtable",
+			type: "module",
+			exports: { ".": "./src/index.ts", "./testing": "./src/testing.ts" },
+		}),
+	);
+	symlinkSync(join(ROOT, "src"), join(modules, "pi-roundtable/src"));
+	symlinkSync(join(ROOT, "node_modules/typebox"), join(modules, "typebox"));
+	symlinkSync(
+		join(ROOT, "node_modules/@types/bun"),
+		join(modules, "@types/bun"),
+	);
+}
+
+const dir = tempDir("roundtable-template-");
+const bun = { version: Bun.version, required: ">=1.3.0" };
+const check = (label: string) => {
+	const typecheck = run(dir.path, [TSC, "--noEmit"]);
+	const test = run(dir.path, ["bun", "test"]);
+	const lint = run(dir.path, [BIOME, "check", "."]);
+	return { label, typecheck, test, lint };
+};
+
+let fresh: ReturnType<typeof check>;
+let grown: ReturnType<typeof check>;
+
+beforeAll(() => {
+	const report = init({ cwd: dir.path, bun, version: "0.1.0" });
+	if (!report.ok) throw new Error(report.problems.join("\n"));
+	link(dir.path);
+	fresh = check("fresh");
+	const added = addPlugin({ cwd: dir.path, name: "second-plugin" });
+	if (!added.ok) throw new Error(added.problems.join("\n"));
+	grown = check("after add plugin");
+}, 120_000);
+afterAll(() => dir.done());
+
+describe("every template rendered into one project", () => {
+	test("typechecks with no edits", () => {
+		expect(fresh.typecheck.output).toBe("");
+		expect(fresh.typecheck.ok).toBe(true);
+	});
+	test("passes its own test with no edits", () => {
+		expect(fresh.test.output).toContain("1 pass");
+		expect(fresh.test.ok).toBe(true);
+	});
+	test("passes the linter it ships with", () => {
+		expect(fresh.lint.output).toContain("No fixes applied");
+		expect(fresh.lint.ok).toBe(true);
+	});
+	test("still typechecks, tests, and lints after `add plugin`", () => {
+		expect(grown.typecheck.output).toBe("");
+		expect(grown.test.output).toContain("2 pass");
+		expect(grown.lint.output).toContain("No fixes applied");
+		expect(grown.typecheck.ok && grown.test.ok && grown.lint.ok).toBe(true);
+	});
+});
+
+test("the generated project's pinned tools match this package's own", () => {
+	const project = JSON.parse(
+		readFileSync(join(dir.path, "package.json"), "utf8"),
+	) as {
+		dependencies: Record<string, string>;
+		devDependencies: Record<string, string>;
+	};
+	const own = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")) as {
+		dependencies: Record<string, string>;
+		devDependencies: Record<string, string>;
+	};
+	expect(project.dependencies.typebox).toBe(own.dependencies.typebox);
+	for (const name of ["typescript", "@biomejs/biome", "@types/bun"])
+		expect(project.devDependencies[name]).toBe(own.devDependencies[name]);
+});
+
+test("no template file is hidden from git by an ignore rule, which would leave a clone unable to init", () => {
+	const inRepository = Bun.spawnSync(["git", "rev-parse", "--git-dir"], {
+		cwd: ROOT,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	// The exported public tree is not a checkout; its own ignore file is packaging/.gitignore.
+	if (inRepository.exitCode !== 0) return;
+	const ignored = Bun.spawnSync(
+		[
+			"git",
+			"ls-files",
+			"--others",
+			"--ignored",
+			"--exclude-standard",
+			"templates",
+		],
+		{ cwd: ROOT, stdout: "pipe", stderr: "pipe" },
+	);
+	expect(ignored.stdout.toString().trim()).toBe("");
+});

package/src/cli/templates.ts

@@ -0,0 +1,119 @@
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+/** The templates the package ships, as real files beside the source. */
+export const TEMPLATES_DIR = join(import.meta.dir, "../../templates");
+
+/** The directory of the plugin template, rendered once for `hello` and again for every `add plugin`. */
+const PLUGIN_DIR = "plugin";
+
+/** What a template file may say, replaced when it is rendered. */
+export interface Substitutions {
+	/** The project's package name. */
+	project: string;
+	/** The exact version of pi-roundtable the project depends on. */
+	version: string;
+}
+
+/** The words a plugin template is written in: the kebab name, its identifier, and its tool prefix. */
+export interface PluginNames {
+	name: string;
+	ident: string;
+	tool: string;
+}
+
+/** A file to write: where, and what. */
+export interface Rendered {
+	path: string;
+	content: string;
+}
+
+/** Files that tools would act on in place are stored with a `.tmpl` suffix; npm also drops `.gitignore`. */
+function targetOf(path: string): string {
+	const name = path.replace(/\.tmpl$/, "");
+	return name.endsWith("_gitignore")
+		? name.replace("_gitignore", ".gitignore")
+		: name;
+}
+
+function filesUnder(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		return entry.isDirectory() ? filesUnder(path) : [path];
+	});
+}
+
+/** `my-notes` as the words a template needs. */
+export function pluginNames(name: string): PluginNames {
+	return {
+		name,
+		ident: name.replace(/-(\w)/g, (_, letter: string) => letter.toUpperCase()),
+		tool: name.replaceAll("-", "_"),
+	};
+}
+
+/** A plugin name is lowercase words joined by dashes, as `definePlugin` requires. */
+export const isPluginName = (name: string): boolean =>
+	/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name);
+
+function fill(text: string, values: Record<string, string>): string {
+	return text.replace(/__([A-Z]+)__/g, (whole, key: string) => {
+		const value = values[key];
+		if (value === undefined)
+			throw new Error(`template placeholder ${whole} has no value`);
+		return value;
+	});
+}
+
+/** The plugin and its test, written for `names`. */
+export function renderPlugin(
+	names: PluginNames,
+	dir = TEMPLATES_DIR,
+): Rendered[] {
+	const values = { NAME: names.name, IDENT: names.ident, TOOL: names.tool };
+	return [
+		["plugin.ts", `plugins/${names.name}.ts`],
+		["plugin.test.ts.tmpl", `plugins/${names.name}.test.ts`],
+	].map(([source, path]) => ({
+		path: path as string,
+		content: fill(
+			readFileSync(join(dir, PLUGIN_DIR, source as string), "utf8"),
+			values,
+		),
+	}));
+}
+
+/** Every file of a new project: the skeleton and the `hello` plugin, paths relative to the project. */
+export function renderProject(
+	substitutions: Substitutions,
+	dir = TEMPLATES_DIR,
+): Rendered[] {
+	if (!existsSync(dir)) throw new Error(`templates are missing: ${dir}`);
+	const values = {
+		PROJECT: substitutions.project,
+		VERSION: substitutions.version,
+	};
+	const skeleton = filesUnder(dir)
+		.map((file) => relative(dir, file))
+		.filter((path) => !path.startsWith(`${PLUGIN_DIR}/`))
+		.map((path) => ({
+			path: targetOf(path),
+			content: fill(readFileSync(join(dir, path), "utf8"), values),
+		}));
+	return [...skeleton, ...renderPlugin(pluginNames("hello"), dir)];
+}
+
+/** Writes rendered files under `root`, creating directories; the caller has checked that none exists. */
+export function writeRendered(root: string, files: readonly Rendered[]): void {
+	for (const file of files) {
+		const target = join(root, file.path);
+		mkdirSync(dirname(target), { recursive: true });
+		writeFileSync(target, file.content);
+	}
+}

package/src/cli/testing/fixtures.ts

@@ -0,0 +1,106 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { RoundtableConfig } from "../../core/config/config.ts";
+import type { DefinedRoundtable } from "../../core/define-roundtable.ts";
+import type { Http, HttpResponse } from "../http.ts";
+import type { Ports } from "../project.ts";
+
+/** A configuration the schema accepts. */
+export const validConfig: RoundtableConfig = {
+	owner: { id: "100000000000000001", name: "Ada" },
+	discord: {
+		token: "bot-token",
+		guild: "900000000000000001",
+		entryChannel: "900000000000000002",
+	},
+	database: { url: "postgres://user:secret@db.example.test:5432/bot" },
+	dataDir: "/data",
+	model: "anthropic/claude-sonnet-5-5",
+	http: { publicUrl: "https://bot.example.test" },
+};
+
+/** A directory that is removed when the test ends; call `done` in `afterEach`. */
+export function tempDir(prefix = "roundtable-cli-"): {
+	path: string;
+	write(file: string, content: string): void;
+	done(): void;
+} {
+	const path = mkdtempSync(join(tmpdir(), prefix));
+	return {
+		path,
+		write(file, content) {
+			mkdirSync(dirname(join(path, file)), { recursive: true });
+			writeFileSync(join(path, file), content);
+		},
+		done: () => rmSync(path, { recursive: true, force: true }),
+	};
+}
+
+/** Ports that hand out `config`, assemble nothing real, and report a login from `source`. */
+export function fakePorts(
+	config: unknown = validConfig,
+	overrides: Partial<Ports> = {},
+): Ports {
+	const defined: DefinedRoundtable = {
+		options: { logger: {} as never },
+		plugins: [{ name: "database", setup: () => ({}) }],
+	};
+	return {
+		loadConfig: async () => config,
+		define: async () => defined,
+		login: async () => "ANTHROPIC_API_KEY",
+		...overrides,
+	};
+}
+
+/** An HTTP client that answers from `routes`, keyed by the path after the host, and fails on any other. */
+export function fakeHttp(
+	routes: Record<string, HttpResponse | Error>,
+): Http & { requests: string[] } {
+	const requests: string[] = [];
+	return {
+		requests,
+		async get(url) {
+			const key = url.replace(/^https?:\/\/[^/]+(\/api\/v10)?/, "") || "/";
+			requests.push(key);
+			const route = routes[key];
+			if (route === undefined) throw new Error(`no route for ${key}`);
+			if (route instanceof Error) throw route;
+			return route;
+		},
+	};
+}
+
+export const BOT_ID = "800000000000000001";
+
+/** Discord as it answers when everything is right: the token is good, the bot is in the guild, with every permission and the intent. */
+export function healthyDiscord(
+	permissions: bigint,
+	guild = validConfig.discord.guild,
+	channel = validConfig.discord.entryChannel,
+): Record<string, HttpResponse> {
+	return {
+		"/users/@me": { status: 200, body: { id: BOT_ID, username: "Bot" } },
+		"/applications/@me": { status: 200, body: { flags: 1 << 18 } },
+		[`/guilds/${guild}`]: {
+			status: 200,
+			body: {
+				name: "Test Guild",
+				owner_id: "100000000000000001",
+				roles: [
+					{ id: guild, permissions: "0" },
+					{ id: "700000000000000001", permissions: String(permissions) },
+				],
+			},
+		},
+		[`/guilds/${guild}/members/${BOT_ID}`]: {
+			status: 200,
+			body: { roles: ["700000000000000001"] },
+		},
+		[`/channels/${channel}`]: {
+			status: 200,
+			body: { id: channel, guild_id: guild, permission_overwrites: [] },
+		},
+	};
+}