pi-roundtable 0.1.0

package/src/cli/checks/database.test.ts

@@ -0,0 +1,117 @@
+import { expect, test } from "bun:test";
+import type { Migration } from "../../core/db/migrations.ts";
+import { MigrationError } from "../../core/errors.ts";
+import { describeDb, testDatabaseUrl } from "../../core/testing/database.ts";
+import { Project } from "../project.ts";
+import { fakePorts, validConfig } from "../testing/fixtures.ts";
+import { checkDatabase, type DatabasePort, postgres } from "./database.ts";
+
+const migration: Migration = { name: "doctor-probe", up: async () => {} };
+const withMigration = (name = "probe") =>
+	new Project(
+		"/x",
+		fakePorts(validConfig, {
+			define: async () => ({
+				options: { logger: {} as never },
+				plugins: [{ name, setup: () => ({}), migrations: [migration] }],
+			}),
+		}),
+	);
+
+test("passes when the database answers and the migrations run, without printing the password", async () => {
+	const asked: unknown[] = [];
+	const port: DatabasePort = {
+		check: async (url, migrations) => void asked.push([url, migrations]),
+	};
+	const result = await checkDatabase(withMigration(), port);
+	expect(result.status).toBe("ok");
+	if (result.status === "ok") {
+		expect(result.detail).toContain("db.example.test:5432/bot");
+		expect(result.detail).not.toContain("secret");
+	}
+	expect(asked).toEqual([[validConfig.database.url, [migration]]]);
+});
+
+test("fails when the database is unreachable, naming it and saying how to start one", async () => {
+	const port: DatabasePort = {
+		check: async () => {
+			throw new Error("connection refused");
+		},
+	};
+	const result = await checkDatabase(withMigration(), port);
+	expect(result.status).toBe("fail");
+	if (result.status === "fail") {
+		expect(result.problem).toContain("db.example.test:5432/bot");
+		expect(result.problem).toContain("connection refused");
+		expect(result.problem).not.toContain("secret");
+		expect(result.fix).toContain("docker compose up -d");
+	}
+});
+
+test("fails when a migration fails, naming it", async () => {
+	const port: DatabasePort = {
+		check: async () => {
+			throw new MigrationError("owner-memory", new Error("permission denied"));
+		},
+	};
+	const result = await checkDatabase(withMigration(), port);
+	expect(result.status).toBe("fail");
+	if (result.status === "fail") {
+		expect(result.problem).toContain("migration owner-memory failed");
+		expect(result.problem).toContain("permission denied");
+	}
+});
+
+test("still tests reachability from the raw url while the configuration is invalid, and skips without a url", async () => {
+	const asked: unknown[] = [];
+	const port: DatabasePort = {
+		check: async (url, migrations) => void asked.push([url, migrations]),
+	};
+	const invalid = new Project(
+		"/x",
+		fakePorts({ database: { url: "postgres://h/d" } }),
+	);
+	const result = await checkDatabase(invalid, port);
+	expect(result.status).toBe("ok");
+	expect(asked).toEqual([["postgres://h/d", undefined]]);
+	const none = await checkDatabase(new Project("/x", fakePorts({})), port);
+	expect(none.status).toBe("skipped");
+});
+
+describeDb("against PostgreSQL", () => {
+	test("runs the migrations inside a rolled-back transaction, including ones that open their own", async () => {
+		const table = `doctor_probe_${Date.now()}`;
+		const run: Migration = {
+			name: "creates",
+			up: async (sql) => {
+				await sql`create table ${sql(table)} (id int)`;
+				await sql.begin(async (inner) => {
+					await inner`insert into ${inner(table)} values (1)`;
+				});
+			},
+		};
+		await postgres.check(testDatabaseUrl, [run]);
+		const pool = new Bun.SQL(testDatabaseUrl, { max: 1 });
+		try {
+			const [found] = await pool`select to_regclass(${table}) as name`;
+			expect(found?.name).toBeNull();
+		} finally {
+			await pool.close();
+		}
+	});
+
+	test("reports a failing migration as a MigrationError and an unreachable server as an error", async () => {
+		const broken: Migration = {
+			name: "broken",
+			up: async (sql) => {
+				await sql`select * from no_such_table_anywhere`;
+			},
+		};
+		await expect(
+			postgres.check(testDatabaseUrl, [broken]),
+		).rejects.toBeInstanceOf(MigrationError);
+		await expect(
+			postgres.check("postgres://nobody@127.0.0.1:1/none", undefined),
+		).rejects.toThrow();
+	});
+});

package/src/cli/checks/database.ts

@@ -0,0 +1,100 @@
+import type { SQL, TransactionSQL } from "bun";
+import type { Migration } from "../../core/db/migrations.ts";
+import { migrate, openPool } from "../../core/db/migrations.ts";
+import { MigrationError } from "../../core/errors.ts";
+import type { Project } from "../project.ts";
+import { fail, ok, type Result, skipped } from "../report.ts";
+
+/** Asks PostgreSQL whether it answers and, given migrations, whether they run. */
+export interface DatabasePort {
+	check(
+		url: string,
+		migrations: readonly Migration[] | undefined,
+	): Promise<void>;
+}
+
+class Rollback extends Error {}
+
+/**
+ * The transaction as a migration sees the pool: a migration that opens its own transaction
+ * with `begin` gets a savepoint of the checking one, which PostgreSQL nests.
+ */
+function nested(transaction: TransactionSQL): SQL {
+	return new Proxy(transaction, {
+		get(target, property) {
+			if (property === "begin")
+				return (...args: Parameters<TransactionSQL["savepoint"]>) =>
+					target.savepoint(...args);
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
+/**
+ * The real port. The migrations run inside a transaction that is always rolled back: DDL in
+ * PostgreSQL is transactional, so what the check proves it runs is exactly what the host runs,
+ * and the database is left as it was.
+ */
+export const postgres: DatabasePort = {
+	async check(url, migrations) {
+		const pool = openPool(url);
+		try {
+			await pool`select 1`;
+			if (!migrations) return;
+			try {
+				await pool.begin(async (transaction) => {
+					await migrate(nested(transaction), migrations);
+					throw new Rollback();
+				});
+			} catch (error) {
+				if (!(error instanceof Rollback)) throw error;
+			}
+		} finally {
+			await pool.close();
+		}
+	},
+};
+
+/** The address without its password, safe to print. */
+function where(url: string): string {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}${parsed.pathname}`;
+	} catch {
+		return "the configured database";
+	}
+}
+
+/** PostgreSQL reachable, and every plugin's migrations able to run on it. */
+export async function checkDatabase(
+	project: Project,
+	port: DatabasePort,
+): Promise<Result> {
+	const url = await project.text("database", "url");
+	if (!url) return skipped("database.url has no value");
+	const assembled = await project.assembled();
+	const migrations = assembled.ok
+		? assembled.value.defined.plugins.flatMap(
+				(plugin) => plugin.migrations ?? [],
+			)
+		: undefined;
+	try {
+		await port.check(url, migrations);
+	} catch (error) {
+		if (error instanceof MigrationError)
+			return fail(
+				`migration ${error.migration} failed: ${String(error.cause)}`,
+				"Fix the migration, or restore the database to the state it expects.",
+			);
+		return fail(
+			`cannot use ${where(url)}: ${error instanceof Error ? error.message : String(error)}`,
+			"Start PostgreSQL (`docker compose up -d` in this project) or correct DATABASE_URL in .env.",
+		);
+	}
+	return ok(
+		migrations
+			? `${where(url)} answers and the migrations run`
+			: `${where(url)} answers; migrations are checked once the configuration is valid`,
+	);
+}

package/src/cli/checks/discord.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+import { PermissionFlagsBits } from "discord.js";
+import { INVITE_PERMISSIONS } from "../discord-api.ts";
+import { Project } from "../project.ts";
+import type { Result } from "../report.ts";
+import {
+	BOT_ID,
+	fakeHttp,
+	fakePorts,
+	healthyDiscord,
+	validConfig,
+} from "../testing/fixtures.ts";
+import {
+	checkChannel,
+	checkGuild,
+	checkIntents,
+	checkToken,
+	Discord,
+} from "./discord.ts";
+
+const guild = validConfig.discord.guild;
+const channel = validConfig.discord.entryChannel;
+const project = (config: unknown = validConfig) =>
+	new Project("/x", fakePorts(config));
+
+function failure(result: Result): string {
+	if (result.status !== "fail")
+		throw new Error(`expected a failure, got ${JSON.stringify(result)}`);
+	return `${result.problem}\n${result.fix}`;
+}
+
+const all = INVITE_PERMISSIONS;
+const bit = (name: keyof typeof PermissionFlagsBits): bigint =>
+	PermissionFlagsBits[name];
+const without = (name: keyof typeof PermissionFlagsBits): bigint =>
+	all & ~bit(name);
+
+describe("Discord token", () => {
+	test("passes and names the bot", async () => {
+		const http = fakeHttp(healthyDiscord(all));
+		const result = await checkToken(new Discord(project(), http));
+		expect(result).toEqual({ status: "ok", detail: "the bot is Bot" });
+	});
+	test("fails on a rejected token with where to reset it", async () => {
+		const http = fakeHttp({ "/users/@me": { status: 401, body: {} } });
+		const text = failure(await checkToken(new Discord(project(), http)));
+		expect(text).toContain("rejected the bot token");
+		expect(text).toContain("DISCORD_TOKEN");
+		expect(text).toContain("discord.com/developers");
+	});
+	test("fails when Discord cannot be reached, without a stack trace", async () => {
+		const http = fakeHttp({ "/users/@me": new Error("getaddrinfo ENOTFOUND") });
+		const text = failure(await checkToken(new Discord(project(), http)));
+		expect(text).toContain("cannot reach discord.com: getaddrinfo ENOTFOUND");
+		expect(text).toContain("network");
+	});
+	test("skips without a token, and sends the token as the bot's authorization", async () => {
+		const none = project({
+			...validConfig,
+			discord: { ...validConfig.discord, token: "" },
+		});
+		expect((await checkToken(new Discord(none, fakeHttp({})))).status).toBe(
+			"skipped",
+		);
+		let seen: Record<string, string> | undefined;
+		await checkToken(
+			new Discord(project(), {
+				get: async (_url, headers) => {
+					seen = headers;
+					return { status: 200, body: { id: BOT_ID } };
+				},
+			}),
+		);
+		expect(seen).toEqual({ Authorization: "Bot bot-token" });
+	});
+	test("asks Discord once for who the bot is however many checks need it", async () => {
+		const http = fakeHttp(healthyDiscord(all));
+		const discord = new Discord(project(), http);
+		await checkToken(discord);
+		await checkGuild(project(), discord);
+		await checkChannel(project(), discord);
+		expect(http.requests.filter((path) => path === "/users/@me")).toHaveLength(
+			1,
+		);
+	});
+});
+
+describe("Discord guild", () => {
+	test("passes when the bot is in the guild", async () => {
+		const http = fakeHttp(healthyDiscord(all));
+		const result = await checkGuild(project(), new Discord(project(), http));
+		expect(result).toEqual({
+			status: "ok",
+			detail: "the bot is in Test Guild",
+		});
+	});
+	test("fails when it is not, with an invitation that asks for what the bot needs", async () => {
+		const http = fakeHttp({
+			...healthyDiscord(all),
+			[`/guilds/${guild}`]: { status: 404, body: { code: 10004 } },
+		});
+		const text = failure(
+			await checkGuild(project(), new Discord(project(), http)),
+		);
+		expect(text).toContain(`not in the guild ${guild}`);
+		expect(text).toContain(`client_id=${BOT_ID}`);
+		expect(text).toContain(`permissions=${INVITE_PERMISSIONS}`);
+	});
+	test("is skipped when the token failed", async () => {
+		const http = fakeHttp({ "/users/@me": { status: 401, body: {} } });
+		expect(
+			(await checkGuild(project(), new Discord(project(), http))).status,
+		).toBe("skipped");
+	});
+});
+
+describe("Discord intents", () => {
+	test("passes with the Message Content intent, granted or limited", async () => {
+		for (const flags of [1 << 18, 1 << 19]) {
+			const http = fakeHttp({
+				...healthyDiscord(all),
+				"/applications/@me": { status: 200, body: { flags } },
+			});
+			expect((await checkIntents(new Discord(project(), http))).status).toBe(
+				"ok",
+			);
+		}
+	});
+	test("fails without it, saying where to turn it on", async () => {
+		const http = fakeHttp({
+			...healthyDiscord(all),
+			"/applications/@me": { status: 200, body: { flags: 0 } },
+		});
+		const text = failure(await checkIntents(new Discord(project(), http)));
+		expect(text).toContain("Message Content intent is off");
+		expect(text).toContain("Bot in https://discord.com/developers");
+	});
+});
+
+describe("Discord channel", () => {
+	const check = (routes: Record<string, never> | object) =>
+		checkChannel(project(), new Discord(project(), fakeHttp(routes as never)));
+	test("passes when the bot has every permission", async () => {
+		expect((await check(healthyDiscord(all))).status).toBe("ok");
+	});
+	test("fails naming the permission the bot lacks, Pin Messages included, and why it is needed", async () => {
+		const text = failure(await check(healthyDiscord(without("PinMessages"))));
+		expect(text).toContain("lacks PinMessages");
+		expect(text).toContain("pin the dashboard");
+	});
+	test("a channel overwrite that denies a permission counts, and an allow restores it", async () => {
+		const pin = bit("PinMessages");
+		const denied = healthyDiscord(all);
+		denied[`/channels/${channel}`] = {
+			status: 200,
+			body: {
+				guild_id: guild,
+				permission_overwrites: [
+					{ id: "700000000000000001", type: 0, allow: "0", deny: String(pin) },
+				],
+			},
+		};
+		expect(failure(await check(denied))).toContain("PinMessages");
+		const restored = healthyDiscord(all);
+		restored[`/channels/${channel}`] = {
+			status: 200,
+			body: {
+				guild_id: guild,
+				permission_overwrites: [
+					{ id: guild, type: 0, allow: "0", deny: String(pin) },
+					{ id: BOT_ID, type: 1, allow: String(pin), deny: "0" },
+				],
+			},
+		};
+		expect((await check(restored)).status).toBe("ok");
+	});
+	test("the owner of the guild and an administrator have every permission", async () => {
+		const administrator = 1n << 3n;
+		expect((await check(healthyDiscord(administrator))).status).toBe("ok");
+	});
+	test("fails when the channel does not exist or is in another guild", async () => {
+		const missing = healthyDiscord(all);
+		missing[`/channels/${channel}`] = { status: 404, body: {} };
+		expect(failure(await check(missing))).toContain("DISCORD_ENTRY_CHANNEL_ID");
+		const elsewhere = healthyDiscord(all);
+		elsewhere[`/channels/${channel}`] = {
+			status: 200,
+			body: { guild_id: "999", permission_overwrites: [] },
+		};
+		expect(failure(await check(elsewhere))).toContain("another guild");
+	});
+	test("is skipped without the channel or guild value", async () => {
+		const empty = project({
+			...validConfig,
+			discord: { ...validConfig.discord, entryChannel: "" },
+		});
+		const result = await checkChannel(empty, new Discord(empty, fakeHttp({})));
+		expect(result.status).toBe("skipped");
+	});
+});

package/src/cli/checks/discord.ts

@@ -0,0 +1,218 @@
+import {
+	channelPermissions,
+	DiscordApi,
+	inviteUrl,
+	REQUIRED_PERMISSIONS,
+} from "../discord-api.ts";
+import type { Http, HttpResponse } from "../http.ts";
+import type { Project } from "../project.ts";
+import { fail, ok, type Result, skipped } from "../report.ts";
+
+const PORTAL = "https://discord.com/developers/applications";
+const MESSAGE_CONTENT_FLAGS = (1 << 18) | (1 << 19);
+
+const object = (value: unknown): Record<string, unknown> =>
+	typeof value === "object" && value !== null
+		? (value as Record<string, unknown>)
+		: {};
+
+type Bot = { id: string; name: string };
+type Step<T> = { ok: true; value: T } | { ok: false; result: Result };
+
+/**
+ * The bot's own view of Discord, asked at most once per fact, so four checks cost four
+ * requests, not ten. A failed step says why once and the checks after it are skipped.
+ */
+export class Discord {
+	readonly #project: Project;
+	readonly #http: Http;
+	#api: Promise<Step<DiscordApi>> | undefined;
+	#bot: Promise<Step<Bot>> | undefined;
+
+	constructor(project: Project, http: Http) {
+		this.#project = project;
+		this.#http = http;
+	}
+
+	async #client(): Promise<Step<DiscordApi>> {
+		const token = await this.#project.text("discord", "token");
+		return token
+			? { ok: true, value: new DiscordApi(this.#http, token) }
+			: { ok: false, result: skipped("discord.token has no value") };
+	}
+
+	/** One request; a network failure becomes a failed result naming the address. */
+	async ask(api: DiscordApi, path: string): Promise<Step<HttpResponse>> {
+		try {
+			return { ok: true, value: await api.get(path) };
+		} catch (error) {
+			return {
+				ok: false,
+				result: fail(
+					`cannot reach discord.com: ${error instanceof Error ? error.message : String(error)}`,
+					"Check the network connection and try again.",
+				),
+			};
+		}
+	}
+
+	api(): Promise<Step<DiscordApi>> {
+		this.#api ??= this.#client();
+		return this.#api;
+	}
+
+	/** Who the token belongs to. */
+	bot(): Promise<Step<Bot>> {
+		this.#bot ??= this.#identify();
+		return this.#bot;
+	}
+
+	async #identify(): Promise<Step<Bot>> {
+		const api = await this.api();
+		if (!api.ok) return api;
+		const answer = await this.ask(api.value, "/users/@me");
+		if (!answer.ok) return answer;
+		const { status, body } = answer.value;
+		if (status === 401)
+			return {
+				ok: false,
+				result: fail(
+					"Discord rejected the bot token.",
+					`Reset it under Bot in ${PORTAL} and put the new one in .env as DISCORD_TOKEN.`,
+				),
+			};
+		const id = object(body).id;
+		if (status !== 200 || typeof id !== "string")
+			return {
+				ok: false,
+				result: fail(
+					`Discord answered ${status} when asked who the token belongs to.`,
+					"Try again in a moment; if it persists, check https://discordstatus.com.",
+				),
+			};
+		return {
+			ok: true,
+			value: { id, name: String(object(body).username ?? id) },
+		};
+	}
+}
+
+/** The token is one Discord accepts. */
+export async function checkToken(discord: Discord): Promise<Result> {
+	const bot = await discord.bot();
+	return bot.ok ? ok(`the bot is ${bot.value.name}`) : bot.result;
+}
+
+/** The bot is a member of the configured guild; the fix is an invitation that asks for what it needs. */
+export async function checkGuild(
+	project: Project,
+	discord: Discord,
+): Promise<Result> {
+	const guild = await project.text("discord", "guild");
+	if (!guild) return skipped("discord.guild has no value");
+	const bot = await discord.bot();
+	if (!bot.ok) return skipped("the token check failed");
+	const api = await discord.api();
+	if (!api.ok) return api.result;
+	const answer = await discord.ask(api.value, `/guilds/${guild}`);
+	if (!answer.ok) return answer.result;
+	const { status, body } = answer.value;
+	if (status === 200) return ok(`the bot is in ${String(object(body).name)}`);
+	if (status === 403 || status === 404)
+		return fail(
+			`the bot is not in the guild ${guild}, or the guild id is wrong.`,
+			`Check DISCORD_GUILD_ID, then invite the bot: ${inviteUrl(bot.value.id)}`,
+		);
+	return fail(
+		`Discord answered ${status} when asked for the guild ${guild}.`,
+		"Try again in a moment.",
+	);
+}
+
+/** The Message Content intent is switched on, without which the agents cannot read the channels. */
+export async function checkIntents(discord: Discord): Promise<Result> {
+	const bot = await discord.bot();
+	if (!bot.ok) return skipped("the token check failed");
+	const api = await discord.api();
+	if (!api.ok) return api.result;
+	const answer = await discord.ask(api.value, "/applications/@me");
+	if (!answer.ok) return answer.result;
+	const flags = object(answer.value.body).flags;
+	if (answer.value.status !== 200 || typeof flags !== "number")
+		return fail(
+			`Discord answered ${answer.value.status} when asked for the application.`,
+			"Try again in a moment.",
+		);
+	if ((flags & MESSAGE_CONTENT_FLAGS) === 0)
+		return fail(
+			"the Message Content intent is off.",
+			`Turn on Message Content Intent under Bot in ${PORTAL}, save, and run the check again.`,
+		);
+	return ok("the Message Content intent is on");
+}
+
+/** The entry channel exists in the guild and the bot may do in it what the agents do. */
+export async function checkChannel(
+	project: Project,
+	discord: Discord,
+): Promise<Result> {
+	const channel = await project.text("discord", "entryChannel");
+	const guild = await project.text("discord", "guild");
+	if (!channel || !guild)
+		return skipped("discord.entryChannel or discord.guild has no value");
+	const bot = await discord.bot();
+	if (!bot.ok) return skipped("the token check failed");
+	const api = await discord.api();
+	if (!api.ok) return api.result;
+	const found = await discord.ask(api.value, `/channels/${channel}`);
+	if (!found.ok) return found.result;
+	const shown = object(found.value.body);
+	if (found.value.status === 403 || found.value.status === 404)
+		return fail(
+			`the bot cannot see a channel ${channel}.`,
+			"Check DISCORD_ENTRY_CHANNEL_ID, and that the bot's role may view the channel.",
+		);
+	if (found.value.status !== 200)
+		return fail(
+			`Discord answered ${found.value.status} when asked for the channel ${channel}.`,
+			"Try again in a moment.",
+		);
+	if (shown.guild_id !== guild)
+		return fail(
+			`the channel ${channel} belongs to another guild.`,
+			"Use a channel of the configured guild for DISCORD_ENTRY_CHANNEL_ID.",
+		);
+	const [guildAnswer, member] = await Promise.all([
+		discord.ask(api.value, `/guilds/${guild}`),
+		discord.ask(api.value, `/guilds/${guild}/members/${bot.value.id}`),
+	]);
+	if (!guildAnswer.ok) return guildAnswer.result;
+	if (!member.ok) return member.result;
+	if (guildAnswer.value.status !== 200 || member.value.status !== 200)
+		return fail(
+			`Discord did not show the bot's roles (${guildAnswer.value.status}, ${member.value.status}).`,
+			"Check that the bot is in the guild, then try again.",
+		);
+	const guildFacts = object(guildAnswer.value.body);
+	const granted = channelPermissions({
+		botId: bot.value.id,
+		guildId: guild,
+		ownerId: String(guildFacts.owner_id),
+		roles: (guildFacts.roles as { id: string; permissions: string }[]) ?? [],
+		memberRoles: (object(member.value.body).roles as string[]) ?? [],
+		overwrites:
+			(shown.permission_overwrites as {
+				id: string;
+				type: number;
+				allow: string;
+				deny: string;
+			}[]) ?? [],
+	});
+	const lacking = REQUIRED_PERMISSIONS.filter(([name]) => !granted.has(name));
+	if (lacking.length > 0)
+		return fail(
+			`in the entry channel the bot lacks ${lacking.map(([name]) => name).join(", ")}.`,
+			`Grant them to the bot's role or in the channel's permissions (${lacking.map(([name, use]) => `${name} to ${use}`).join("; ")}).`,
+		);
+	return ok("the bot has every permission it needs there");
+}

package/src/cli/checks/environment.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fail, ok, type Result, skipped } from "../report.ts";
+
+/** The variables `.env.example` asks for: its uncommented `NAME=` lines. */
+export function requiredVariables(example: string): string[] {
+	return [...example.matchAll(/^([A-Z][A-Z0-9_]*)=/gm)].map(
+		(match) => match[1] as string,
+	);
+}
+
+/** Every variable `.env.example` lists has a value, so a missing credential is named before anything tries to use it. */
+export function checkEnvironment(
+	cwd: string,
+	env: Record<string, string | undefined>,
+): Result {
+	const path = join(cwd, ".env.example");
+	if (!existsSync(path)) return skipped("this project has no .env.example");
+	const missing = requiredVariables(readFileSync(path, "utf8")).filter(
+		(name) => (env[name] ?? "").trim() === "",
+	);
+	if (missing.length === 0) return ok(".env has a value for every variable");
+	return fail(
+		`no value for ${missing.join(", ")}.`,
+		`${existsSync(join(cwd, ".env")) ? "Fill them in .env" : "Copy .env.example to .env and fill them in"}; .env.example says where each one comes from.`,
+	);
+}

package/src/cli/checks/model.ts

@@ -0,0 +1,28 @@
+import { parseModelRef } from "../../core/models.ts";
+import type { Ports, Project } from "../project.ts";
+import { fail, ok, type Result, skipped } from "../report.ts";
+
+/** A login exists for the provider of the configured model: an API key variable or a stored login. */
+export async function checkModelLogin(
+	project: Project,
+	ports: Pick<Ports, "login">,
+): Promise<Result> {
+	const model = await project.text("model");
+	if (!model) return skipped("model has no value");
+	const ref = parseModelRef(model);
+	if (!ref)
+		return fail(
+			`the model ${JSON.stringify(model)} is not written <provider>/<id>.`,
+			"Write it like anthropic/claude-sonnet-5-5 in MODEL in .env.",
+		);
+	const dir = await project.text("agentDir");
+	const dataDir = await project.text("dataDir");
+	const agentDir = dir ?? (dataDir ? `${dataDir}/pi` : undefined);
+	if (!agentDir) return skipped("dataDir has no value");
+	const source = await ports.login(agentDir, ref.provider);
+	if (source) return ok(`${ref.provider} login from ${source}`);
+	return fail(
+		`no login for ${ref.provider}, the provider of ${model}.`,
+		`Set the provider's API key in .env (ANTHROPIC_API_KEY for anthropic, OPENAI_API_KEY for openai), or sign in with Pi so ${agentDir}/auth.json holds it.`,
+	);
+}