pi-roundtable 0.7.19 → 0.9.0

package/src/cli/cli.ts

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { resolveConfig } from "../core/config/config.ts";
 import type { DefinedRoundtable } from "../core/define-roundtable.ts";
 import { Roundtable } from "../core/host.ts";
+import { declaredIdentities } from "../core/identity/plugin-identities.ts";
 import { addPackage } from "./add-package.ts";
 import { addPlugin } from "./add-plugin.ts";
 import type { BunFacts } from "./checks/bun.ts";
@@ -10,11 +12,24 @@ import { doctor } from "./doctor.ts";
 import { fetchHttp } from "./http.ts";
 import { init } from "./init.ts";
 import { type PackagePorts, piPackagePorts } from "./pi-packages.ts";
-import { loadConfigFile, type Ports } from "./project.ts";
+import {
+	type Configured,
+	type ConfiguredIdentities,
+	PRINCIPAL_USAGE,
+	principalCommand,
+} from "./principal.ts";
+import {
+	CONFIG_FILE,
+	loadConfigFile,
+	loadDefault,
+	type Ports,
+	Project,
+} from "./project.ts";
 import { formatOutcomes } from "./report.ts";
 import { assemble, providerLogin } from "./runtime.ts";
 import { start } from "./start.ts";
-import { OFFICIAL_PLUGINS } from "./templates.ts";
+import { ADAPTERS, isAdapter, OFFICIAL_PLUGINS } from "./templates.ts";
+import { upgrade } from "./upgrade.ts";
 
 /** What the command line reads from its surroundings; tests replace every part. */
 export interface CliEnvironment {
@@ -32,7 +47,9 @@ export interface CliEnvironment {
 
 const USAGE = `roundtable: a Discord agent server on Pi
 
-  roundtable init [dir]         create a project (default: the current directory)
+  roundtable init [dir] [--adapter discord|web]
+                                create a project (default: the current directory) that talks
+                                through Discord (the default) or through the web chat
   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
@@ -40,6 +57,12 @@ const USAGE = `roundtable: a Discord agent server on Pi
                                 which are copied in ready to run instead of the template
   roundtable add package <spec> install a Pi package with bun add, and add plugins/<name>.ts that
                                 loads it and gives its tools to every agent turn
+  roundtable upgrade [--write [--unchecked]]
+                                show roundtable.config.ts rewritten in the 0.9 form (owner and
+                                speakers as access, discord as an adapter); --write writes it once
+                                it is checked to serve the same people, which needs the
+                                environment the host runs with; --unchecked writes it unchecked
+${PRINCIPAL_USAGE}
 `;
 
 /** The package's own version and the Bun range it needs, from the package.json beside the source. */
@@ -108,13 +131,22 @@ export async function runCli(
 		return 0;
 	}
 	if (command === "init") {
-		const [dir, ...extra] = rest;
-		if (extra.length > 0) return usage(io, "init takes at most one directory");
+		const at = rest.indexOf("--adapter");
+		const adapter = at === -1 ? "discord" : rest[at + 1];
+		if (adapter === undefined || !isAdapter(adapter))
+			return usage(
+				io,
+				`--adapter takes one of ${ADAPTERS.join(", ")}, not ${JSON.stringify(adapter ?? "")}`,
+			);
+		const [dir, ...extra] = at === -1 ? rest : rest.toSpliced(at, 2);
+		if (extra.length > 0 || dir?.startsWith("-"))
+			return usage(io, "init takes at most one directory");
 		const report = init({
 			cwd: io.cwd,
 			...(dir === undefined ? {} : { dir }),
 			bun: io.bun(),
 			version: io.version(),
+			adapter,
 		});
 		if (!report.ok) {
 			for (const line of report.problems) io.err(line);
@@ -190,9 +222,102 @@ export async function runCli(
 		}
 		return 0;
 	}
+	if (command === "upgrade") {
+		const write = rest.includes("--write");
+		const unchecked = rest.includes("--unchecked");
+		if (rest.some((arg) => arg !== "--write" && arg !== "--unchecked"))
+			return usage(io, "upgrade takes only --write and --unchecked");
+		if (unchecked && !write) return usage(io, "--unchecked goes with --write");
+		return runUpgrade(io, write, unchecked);
+	}
+	if (command === "principal") {
+		const project = new Project(resolve(io.cwd), io.ports);
+		const raw = await project.raw();
+		if (!raw.ok) {
+			for (const line of formatOutcomes([
+				{ name: "configuration", result: raw.failure },
+			]))
+				io.err(line);
+			return 1;
+		}
+		const url = await project.text("database", "url");
+		if (!url) {
+			io.err(
+				`database.url has no value in ${CONFIG_FILE}; the principals live in the host's database. Set DATABASE_URL in .env.`,
+			);
+			return 1;
+		}
+		return principalCommand(url, rest, io, configured(raw.value));
+	}
 	return usage(io, `unknown command ${JSON.stringify(command)}`);
 }
 
+/**
+ * The owners the configuration lists and the identities its plugins declare, read by its schema
+ * alone: its plugins and model runtime are not assembled, so their failures do not pass for a
+ * configuration that does not load. Identities the start would refuse are unknown.
+ */
+function configured(value: unknown): Configured {
+	let config: ReturnType<typeof resolveConfig>;
+	try {
+		config = resolveConfig(value);
+	} catch {
+		return { owners: undefined, identities: undefined };
+	}
+	let identities: ConfiguredIdentities;
+	try {
+		identities = declaredIdentities(config.plugins);
+	} catch {
+		identities = undefined;
+	}
+	return { owners: config.access.owners, identities };
+}
+
+async function runUpgrade(
+	io: CliEnvironment,
+	write: boolean,
+	unchecked: boolean,
+): Promise<number> {
+	const report = await upgrade({
+		cwd: resolve(io.cwd),
+		write,
+		unchecked,
+		load: loadDefault,
+	});
+	if (!report.ok) {
+		for (const line of report.problems) io.err(line);
+		io.err(`${CONFIG_FILE} was not changed.`);
+		return 1;
+	}
+	if (report.changes.length === 0) {
+		io.out(
+			`${CONFIG_FILE} is already in the 0.9 form; there is nothing to change.`,
+		);
+		return 0;
+	}
+	io.out(`${CONFIG_FILE} in the 0.9 form:`);
+	for (const change of report.changes) io.out(`  - ${change}`);
+	io.out("");
+	for (const line of report.diff) io.out(line);
+	io.out("");
+	for (const note of report.notes) io.out(`Note: ${note}.`);
+	io.out(
+		"same" in report.verified
+			? "Checked: the rewrite serves the same owners, admins, and members, with the same Discord settings."
+			: `Not checked: ${report.verified.skipped}.`,
+	);
+	if (report.written && "skipped" in report.verified)
+		io.err(
+			`Warning: written without the check, as --unchecked asked. Nothing confirmed that the host serves the same owners, admins, and members as before; read the diff above, and run roundtable doctor with the environment the host runs with.`,
+		);
+	io.out(
+		report.written
+			? `Wrote ${CONFIG_FILE}; no other file was changed.`
+			: `Nothing was written. Run roundtable upgrade --write to write it.`,
+	);
+	return 0;
+}
+
 function usage(io: CliEnvironment, message: string): number {
 	io.err(message);
 	io.err(USAGE);

package/src/cli/config-edit.ts

@@ -1,7 +1,7 @@
 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 {
+export interface Node {
 	type: string;
 	start: number;
 	end: number;
@@ -20,7 +20,7 @@ const WRAPPERS = new Set([
 	"ParenthesizedExpression",
 ]);
 
-const child = (node: Node, key: string): Node | undefined => {
+export const child = (node: Node, key: string): Node | undefined => {
 	const value = node[key];
 	return typeof value === "object" && value !== null
 		? (value as Node)
@@ -28,35 +28,53 @@ const child = (node: Node, key: string): Node | undefined => {
 };
 
 /** The expression under `satisfies`, `as`, `!`, and parentheses. */
-function unwrap(node: Node | undefined): Node | undefined {
+export 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[] {
+/** A parsed module: its top-level statements, and every comment in it. */
+export interface ParsedModule {
+	body: Node[];
+	comments: Node[];
+}
+
+/** The module parsed, or a ConfigEditError saying it does not parse and what to do by hand, `instead`. */
+export function parseConfig(
+	source: string,
+	file: string,
+	instead: string,
+): ParsedModule {
 	try {
-		// SAFETY: every node the parser builds has a type, start, and end, which is all Node states.
-		return parse(source, {
+		const parsed = parse(source, {
 			sourceType: "module",
 			plugins: ["typescript"],
-		}).program.body as unknown as Node[];
+		});
+		// SAFETY: every node the parser builds has a type, start, and end, which is all Node states.
+		return {
+			body: parsed.program.body as unknown as Node[],
+			comments: (parsed.comments ?? []) 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.`,
+			`${file} does not parse (${error instanceof Error ? error.message : String(error)}). Fix it, or ${instead}.`,
 		);
 	}
 }
 
-const nameOf = (node: Node | undefined): string | undefined => {
+const parseModule = (source: string, file: string): Node[] =>
+	parseConfig(source, file, "add the plugin to its list by hand").body;
+
+export 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> {
+export function boundNames(body: readonly Node[]): Set<string> {
 	const names = new Set<string>();
 	for (const statement of body) {
 		const declaration =
@@ -80,7 +98,7 @@ function boundNames(body: readonly Node[]): Set<string> {
 }
 
 /** The object the config exports: the default export itself, or the top-level constant it names. */
-function exportedObject(body: readonly Node[]): Node | undefined {
+export function exportedObject(body: readonly Node[]): Node | undefined {
 	const exported = body.find(
 		(node) => node.type === "ExportDefaultDeclaration",
 	);
@@ -112,7 +130,7 @@ function pluginList(object: Node): Node | undefined {
 	return undefined;
 }
 
-interface Insertion {
+export interface Insertion {
 	at: number;
 	text: string;
 	/** How many characters from `at` the text replaces; none when it only inserts. */
@@ -162,7 +180,11 @@ function expandedList(
 }
 
 /** The text to add so `ident` joins the list, in the list's own layout. */
-function listInsertion(source: string, list: Node, ident: string): Insertion {
+export function listInsertion(
+	source: string,
+	list: Node,
+	ident: string,
+): Insertion {
 	const elements = (list.elements as (Node | null)[]).filter(
 		(element): element is Node => element !== null,
 	);
@@ -205,6 +227,54 @@ function importInsertion(
 		: { at: 0, text: `${line}\n\n` };
 }
 
+/** Where an import of a package goes: after the package imports that sort before it, else first. */
+export function packageImport(
+	body: readonly Node[],
+	specifier: string,
+	line: string,
+): Insertion {
+	const imports = body.filter((node) => node.type === "ImportDeclaration");
+	const from = (node: Node) => String(child(node, "source")?.value ?? "");
+	const before = imports
+		.filter((node) => !from(node).startsWith(".") && from(node) < specifier)
+		.at(-1);
+	if (before) return { at: before.end, text: `\n${line}` };
+	const first = imports[0];
+	return first
+		? { at: first.start, text: `${line}\n` }
+		: { at: 0, text: `${line}\n\n` };
+}
+
+/** Whether the module imports `name` from `specifier` under that same name. */
+export function importsName(
+	body: readonly Node[],
+	specifier: string,
+	name: string,
+): boolean {
+	return body.some(
+		(node) =>
+			node.type === "ImportDeclaration" &&
+			child(node, "source")?.value === specifier &&
+			(node.specifiers as Node[]).some(
+				(imported) =>
+					imported.type === "ImportSpecifier" &&
+					nameOf(child(imported, "imported")) === name &&
+					nameOf(child(imported, "local")) === name,
+			),
+	);
+}
+
+/** Whether the file imports anything from `specifier`. */
+export const importsFrom = (
+	body: readonly Node[],
+	specifier: string,
+): boolean =>
+	body.some(
+		(node) =>
+			node.type === "ImportDeclaration" &&
+			child(node, "source")?.value === specifier,
+	);
+
 /**
  * Adds the plugin's import line and lists it in the `plugins` array of the default export, in the
  * file's own layout; a one-line list that would pass 80 columns is put one element a line. It

package/src/cli/doctor.ts

@@ -9,12 +9,20 @@ import {
 	Discord,
 } from "./checks/discord.ts";
 import { checkEnvironment } from "./checks/environment.ts";
+import { checkAccess, checkPrincipals } from "./checks/identity.ts";
 import { checkImageProvider } from "./checks/images.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";
+import {
+	type Check,
+	failed,
+	type Outcome,
+	type Result,
+	runChecks,
+	skipped,
+} from "./report.ts";
 
 export interface DoctorInputs {
 	cwd: string;
@@ -39,6 +47,11 @@ export function buildChecks(
 ): Check[] {
 	const { cwd, env, bun, ports, database, http, reachable } = inputs;
 	const discord = new Discord(project, http);
+	// A project without Discord asks Discord nothing.
+	const ifDiscord = (run: () => Promise<Result>) => async (): Promise<Result> =>
+		(await project.leavesOut("discord"))
+			? skipped("no Discord is configured")
+			: run();
 	return [
 		{ name: "Bun", offline: true, run: async () => checkBun(bun) },
 		{
@@ -52,6 +65,7 @@ export function buildChecks(
 			run: () => checkConfiguration(project),
 		},
 		{ name: "plugins", offline: true, run: () => checkPlugins(project) },
+		{ name: "access", offline: true, run: () => checkAccess(project) },
 		{
 			name: "image provider",
 			offline: true,
@@ -62,21 +76,30 @@ export function buildChecks(
 			offline: false,
 			run: () => checkDatabase(project, database),
 		},
-		{ name: "Discord token", offline: false, run: () => checkToken(discord) },
+		{
+			name: "principals",
+			offline: false,
+			run: () => checkPrincipals(project, database),
+		},
+		{
+			name: "Discord token",
+			offline: false,
+			run: ifDiscord(() => checkToken(discord)),
+		},
 		{
 			name: "Discord guild",
 			offline: false,
-			run: () => checkGuild(project, discord),
+			run: ifDiscord(() => checkGuild(project, discord)),
 		},
 		{
 			name: "Discord intents",
 			offline: false,
-			run: () => checkIntents(discord),
+			run: ifDiscord(() => checkIntents(discord)),
 		},
 		{
 			name: "Discord channel",
 			offline: false,
-			run: () => checkChannel(project, discord),
+			run: ifDiscord(() => checkChannel(project, discord)),
 		},
 		{
 			name: "model login",

package/src/cli/init.ts

@@ -1,7 +1,12 @@
 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";
+import {
+	type Adapter,
+	type Rendered,
+	renderProject,
+	writeRendered,
+} from "./templates.ts";
 
 export interface InitInputs {
 	cwd: string;
@@ -12,6 +17,8 @@ export interface InitInputs {
 	version: string;
 	/** Where the templates are; default the package's own. */
 	templates?: string;
+	/** The chat network the project talks through; default Discord. */
+	adapter?: Adapter;
 }
 
 export interface InitReport {
@@ -61,6 +68,7 @@ export function init(inputs: InitInputs): InitReport {
 	const files: Rendered[] = renderProject(
 		{ project: projectName(root), version: inputs.version },
 		inputs.templates,
+		inputs.adapter,
 	);
 	const existing = files
 		.map((file) => file.path)

package/src/cli/line-diff.ts

@@ -0,0 +1,72 @@
+/** Every line of `before` and `after` in order: kept, removed, or added. */
+function lineOps(
+	before: readonly string[],
+	after: readonly string[],
+): { kind: " " | "-" | "+"; line: string }[] {
+	// The longest common subsequence, from the end, so the walk below reads forward.
+	const rows = before.length + 1;
+	const columns = after.length + 1;
+	const common = new Uint32Array(rows * columns);
+	for (let i = before.length - 1; i >= 0; i--)
+		for (let j = after.length - 1; j >= 0; j--)
+			common[i * columns + j] =
+				before[i] === after[j]
+					? (common[(i + 1) * columns + j + 1] ?? 0) + 1
+					: Math.max(
+							common[(i + 1) * columns + j] ?? 0,
+							common[i * columns + j + 1] ?? 0,
+						);
+	const ops: { kind: " " | "-" | "+"; line: string }[] = [];
+	let i = 0;
+	let j = 0;
+	while (i < before.length || j < after.length) {
+		if (i < before.length && j < after.length && before[i] === after[j]) {
+			ops.push({ kind: " ", line: before[i++] ?? "" });
+			j++;
+		} else if (
+			j < after.length &&
+			(i === before.length ||
+				(common[i * columns + j + 1] ?? 0) >
+					(common[(i + 1) * columns + j] ?? 0))
+		)
+			ops.push({ kind: "+", line: after[j++] ?? "" });
+		else ops.push({ kind: "-", line: before[i++] ?? "" });
+	}
+	return ops;
+}
+
+const CONTEXT = 3;
+
+/** The change from `before` to `after` as a unified diff with three lines of context; empty when they are the same. */
+export function lineDiff(
+	before: string,
+	after: string,
+	file: string,
+): string[] {
+	const ops = lineOps(before.split("\n"), after.split("\n"));
+	const changed = ops.flatMap((op, index) => (op.kind === " " ? [] : [index]));
+	if (changed.length === 0) return [];
+	// Changes closer than twice the context share a hunk.
+	const hunks: [number, number][] = [];
+	for (const index of changed) {
+		const last = hunks.at(-1);
+		if (last && index - last[1] <= 2 * CONTEXT) last[1] = index;
+		else hunks.push([index, index]);
+	}
+	const lines = [`--- ${file}`, `+++ ${file} (upgraded)`];
+	for (const [first, last] of hunks) {
+		const start = Math.max(0, first - CONTEXT);
+		const end = Math.min(ops.length - 1, last + CONTEXT);
+		const before = ops.slice(0, start);
+		const span = ops.slice(start, end + 1);
+		const count = (list: typeof ops, kind: "-" | "+") =>
+			list.filter((op) => op.kind !== (kind === "-" ? "+" : "-")).length;
+		const oldLength = count(span, "-");
+		const newLength = count(span, "+");
+		lines.push(
+			`@@ -${count(before, "-") + (oldLength > 0 ? 1 : 0)},${oldLength} +${count(before, "+") + (newLength > 0 ? 1 : 0)},${newLength} @@`,
+			...span.map((op) => `${op.kind}${op.line}`),
+		);
+	}
+	return lines;
+}