Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/ask/__tests__/contract.test.ts

Raw
import { fileURLToPath } from "node:url";
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
import { visibleWidth } from "@earendil-works/pi-tui";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
	createPiSession,
	type PiSession,
} from "../../../test/fixture/create-pi-session.ts";
import { askInTui } from "../ask-overlay.ts";
import { __test } from "../index.ts";

let session: PiSession | undefined;

const KEYS: Record<string, string> = {
	"tui.select.confirm": "\r",
	"tui.select.cancel": "\x1b",
	"tui.select.up": "\x1b[A",
	"tui.select.down": "\x1b[B",
	"tui.input.tab": "\t",
};

function tuiSession() {
	let component:
		| {
				handleInput: (data: string) => void;
				handleMouse?: (event: {
					type: "press" | "click";
					button: "left";
					x: number;
					y: number;
					screenX: number;
					screenY: number;
					width: number;
					height: number;
					shift: boolean;
					alt: boolean;
					ctrl: boolean;
				}) => { handled?: boolean } | undefined;
				render: (width: number) => string[];
		  }
		| undefined;
	let options: unknown;
	const custom = (
		factory: (
			tui: unknown,
			theme: unknown,
			keybindings: unknown,
			done: (value: never) => void,
		) => unknown,
		customOptions?: unknown,
	) =>
		new Promise((resolve) => {
			options = customOptions;
			component = factory(
				{ requestRender() {}, terminal: { rows: 40 } },
				{
					fg: (_style: string, text: string) => text,
					bold: (text: string) => text,
				},
				{
					matches: (data: string, action: string) => KEYS[action] === data,
				},
				resolve,
			) as typeof component;
		});
	const ctx = {
		hasUI: true,
		mode: "tui",
		ui: { custom },
	} as unknown as ExtensionContext;
	return { ctx, component: () => component, options: () => options };
}

afterEach(async () => {
	await session?.dispose();
	session = undefined;
});

function fakeCtx(
	ui: {
		select?: (
			title: string,
			entries: string[],
			options?: unknown,
		) => Promise<string | undefined>;
		input?: (
			title: string,
			placeholder?: string,
			options?: unknown,
		) => Promise<string | undefined>;
		confirm?: (
			title: string,
			message: string,
			options?: unknown,
		) => Promise<boolean>;
	},
	overrides: Record<string, unknown> = {},
): ExtensionContext {
	return {
		hasUI: true,
		mode: "rpc",
		ui: {
			select: ui.select ?? (async () => undefined),
			input: ui.input ?? (async () => undefined),
			confirm: ui.confirm ?? (async () => false),
		},
		...overrides,
	} as ExtensionContext;
}

function mouseEvent(type: "press" | "click", y: number, width = 80) {
	return {
		type,
		button: "left" as const,
		x: 1,
		y,
		screenX: 1,
		screenY: y,
		width,
		height: 40,
		shift: false,
		alt: false,
		ctrl: false,
	};
}

function singleQuestion() {
	return __test.normalizeQuestions([
		{
			id: "db",
			header: "Database",
			question: "Which database?",
			options: [
				{ label: "Postgres (Recommended)", description: "Relational." },
				{ label: "SQLite", description: "Embedded." },
			],
		},
	]);
}

describe("ask extension", () => {
	it("loads in real Pi extension runtime and registers ask_user_question", async () => {
		session = await createPiSession({
			extensionPaths: [fileURLToPath(new URL("../index.ts", import.meta.url))],
		});
		const tool =
			session.extensions[0]!.tools.get("ask_user_question")?.definition;
		expect(tool).toBeDefined();
		if (!tool) throw new Error("tool missing");
		expect(tool.exposure).toBe("model-only");
		expect(tool.annotations?.readOnlyHint).toBe(true);
		expect(tool.description).toContain(
			"Without an interactive UI or a connected voice question provider",
		);
		expect(tool.promptGuidelines).toBeDefined();
		if (!tool.promptGuidelines) throw new Error("promptGuidelines missing");
		expect(
			tool.promptGuidelines.every((guideline: string) =>
				guideline.includes("ask_user_question"),
			),
		).toBe(true);
	});

	it("terminates on cancel and reports missing UI at tool level", async () => {
		session = await createPiSession({
			extensionPaths: [fileURLToPath(new URL("../index.ts", import.meta.url))],
		});
		const tool = session.extensions[0]!.tools.get("ask_user_question");
		const definition = tool?.definition;
		expect(definition).toBeDefined();
		if (!definition) throw new Error("definition missing");
		const params = {
			questions: [
				{
					question: "Q?",
					options: [
						{ label: "A", description: "a" },
						{ label: "B", description: "b" },
					],
				},
			],
		};
		const runner = session.session.extensionRunner;
		const cancelled = await definition.execute(
			"id",
			params,
			undefined,
			undefined,
			{ ...runner.createToolContext("id", undefined), ...fakeCtx({}) },
		);
		expect(cancelled.terminate).toBe(true);
		const cancelledContent = cancelled.content[0];
		if (cancelledContent?.type !== "text")
			throw new Error("expected text content");
		expect(JSON.parse(cancelledContent.text).status).toBe("cancelled");

		const unavailable = await definition.execute(
			"id",
			params,
			undefined,
			undefined,
			{
				...runner.createToolContext("id", undefined),
				...fakeCtx({}, { hasUI: false }),
			},
		);
		const unavailableContent = unavailable.content[0];
		if (unavailableContent?.type !== "text")
			throw new Error("expected text content");
		expect(JSON.parse(unavailableContent.text).status).toBe("unavailable");

		const infrastructureError = new Error("UI transport failed");
		await expect(
			definition.execute("id", params, undefined, undefined, {
				...runner.createToolContext("id", undefined),
				...fakeCtx({
					select: async () => {
						throw infrastructureError;
					},
				}),
			}),
		).rejects.toBe(infrastructureError);
		const controller = new AbortController();
		const aborted = await definition.execute(
			"cancelled",
			params,
			controller.signal,
			undefined,
			{
				...runner.createToolContext("cancelled", controller.signal),
				...fakeCtx({
					select: async () => {
						controller.abort();
						throw controller.signal.reason;
					},
				}),
			},
		);
		expect(aborted).toMatchObject({
			terminate: true,
			details: { status: "cancelled" },
		});
	});
});

describe("normalizeQuestions", () => {
	it("derives key and header and strips model-supplied Other options", () => {
		const [question] = __test.normalizeQuestions([
			{
				question: "Which database?",
				options: [
					{ label: "Postgres (Recommended)", description: "Relational." },
					{ label: "Other", description: "ignored" },
				],
			},
		]);
		if (!question) throw new Error("question missing");
		expect(question.key).toBe("Which database?");
		expect(question.header).toBe("Which databa");
		expect(question.options).toHaveLength(1);
		expect(question.options[0]!.label).toBe("Postgres (Recommended)");
	});

	it("prefers id for key and header, dedupes keys, defaults multiSelect", () => {
		const [first, second] = __test.normalizeQuestions([
			{
				id: "deploy",
				header: "Target",
				question: "Deploy where?",
				options: [
					{ label: "A", description: "a" },
					{ label: "B", description: "b" },
				],
			},
			{
				id: "deploy",
				question: "Again?",
				options: [
					{ label: "C", description: "c" },
					{ label: "D", description: "d" },
				],
			},
		]);
		if (!first || !second) throw new Error("questions missing");
		expect(first.key).toBe("deploy");
		expect(first.header).toBe("Target");
		expect(first.multiSelect).toBe(false);
		expect(second.key).toBe("deploy-2");
	});

	it("rejects empty questions and questions without usable options", () => {
		expect(() => __test.normalizeQuestions([])).toThrow(/1-4 questions/);
		expect(() =>
			__test.normalizeQuestions([
				{
					question: "Q?",
					options: [{ label: "Other", description: "x" }],
				},
			]),
		).toThrow(/no usable options/);
	});
});

describe("runAskFlow", () => {
	it("answers single-select with the chosen label and offers Other", async () => {
		const calls: Array<[string, string[]]> = [];
		const result = await __test.runAskFlow(
			singleQuestion(),
			fakeCtx({
				select: async (title, entries) => {
					calls.push([title, entries]);
					return entries[0];
				},
			}),
		);
		expect(result).toEqual({
			status: "answered",
			answers: { db: { answers: ["Postgres (Recommended)"] } },
		});
		expect(calls[0]![0]).toBe("Question 1/1 · Database");
		expect(calls[0]![1]).toContain(__test.OTHER_LABEL);
	});

	it("routes Other through free-text input and trims it", async () => {
		const result = await __test.runAskFlow(
			singleQuestion(),
			fakeCtx({
				select: async (_title, entries) => entries.at(-1) ?? __test.OTHER_LABEL,
				input: async () => "  Whatever fits  ",
			}),
		);
		expect(result).toEqual({
			status: "answered",
			answers: { db: { answers: ["Whatever fits"] } },
		});
	});

	it("cancels the whole call when any dialog is dismissed", async () => {
		const result = await __test.runAskFlow(
			singleQuestion(),
			fakeCtx({
				select: async () => undefined,
				input: async () => "x",
			}),
		);
		expect(result).toEqual({ status: "cancelled" });
	});

	it("collects multi-select confirms, then Done", async () => {
		const picks = [true, false];
		const questions = __test.normalizeQuestions([
			{
				id: "feat",
				question: "Which features?",
				multiSelect: true,
				options: [
					{ label: "Auth", description: "a" },
					{ label: "Audit", description: "b" },
				],
			},
		]);
		const result = await __test.runAskFlow(
			questions,
			fakeCtx({
				select: async (_title, entries) =>
					entries[0] === "Done" ? "Done" : undefined,
				confirm: async () => picks.shift() ?? false,
			}),
		);
		expect(result).toEqual({
			status: "answered",
			answers: { feat: { answers: ["Auth"] } },
		});
	});
});

describe("askInTui cancellation lifecycle", () => {
	type CustomFactory = (
		tui: unknown,
		theme: unknown,
		keybindings: unknown,
		done: (value: unknown) => void,
	) => unknown;
	it("does not open a dialog for a pre-aborted signal", async () => {
		const controller = new AbortController();
		controller.abort();
		let opens = 0;
		const ctx = {
			ui: {
				custom: () => {
					opens++;
					return Promise.resolve(undefined);
				},
			},
		} as unknown as ExtensionContext;

		await expect(
			askInTui("Question", singleQuestion()[0]!, ctx, controller.signal),
		).resolves.toBeUndefined();
		expect(opens).toBe(0);
	});

	it("closes its own covered dialog on abort and removes abort listener", async () => {
		const controller = new AbortController();
		const removeListener = vi.spyOn(controller.signal, "removeEventListener");
		const mounted: unknown[] = [];
		const dialogs: Array<{ close: (value?: unknown) => void }> = [];
		const custom = (factory: CustomFactory) =>
			new Promise((resolve) => {
				let component: unknown;
				let closed = false;
				const close = (value?: unknown) => {
					if (closed) return;
					closed = true;
					const index = mounted.indexOf(component);
					if (index >= 0) mounted.splice(index, 1);
					resolve(value);
				};
				dialogs.push({ close });
				component = factory(
					{},
					{
						fg: (_style: string, text: string) => text,
						bold: (text: string) => text,
					},
					{ matches: () => false },
					close,
				);
				queueMicrotask(() => {
					if (!closed) mounted.push(component);
				});
			});
		const ctx = { ui: { custom } } as unknown as ExtensionContext;
		const ask = askInTui(
			"Question",
			singleQuestion()[0]!,
			ctx,
			controller.signal,
		);
		await Promise.resolve();
		const other = ctx.ui.custom(() => ({ render: () => [], invalidate() {} }));
		await Promise.resolve();
		expect(mounted).toHaveLength(2);

		controller.abort();
		await expect(ask).resolves.toBeUndefined();
		expect(mounted).toHaveLength(1);
		dialogs[1]!.close();
		await other;
		await Promise.resolve();
		expect(mounted).toHaveLength(0);
		expect(removeListener).toHaveBeenCalled();
	});

	it("removes the abort listener after an ordinary answer", async () => {
		const controller = new AbortController();
		const removeListener = vi.spyOn(controller.signal, "removeEventListener");
		const tui = tuiSession();
		const answer = askInTui(
			"Question",
			singleQuestion()[0]!,
			tui.ctx,
			controller.signal,
		);
		tui.component()?.handleInput(KEYS["tui.select.confirm"]!);
		await expect(answer).resolves.toEqual({
			answers: ["Postgres (Recommended)"],
		});
		expect(tui.options()).toEqual({
			blocked: { kind: "question", message: "Which database?" },
		});
		expect(removeListener).toHaveBeenCalledWith("abort", expect.any(Function));
		controller.abort();
	});

	it("settles once when abort races component mounting", async () => {
		const controller = new AbortController();
		let doneCalls = 0;
		let nativeDone: ((value: unknown) => void) | undefined;
		const ctx = {
			ui: {
				custom: (factory: CustomFactory) => {
					let resolve!: (value: unknown) => void;
					let nativeClosed = false;
					const promise = new Promise((res) => (resolve = res));
					const done = (nativeValue: unknown) => {
						if (nativeClosed) return;
						nativeClosed = true;
						doneCalls++;
						resolve(nativeValue);
					};
					const component = factory(
						{},
						{
							fg: (_style: string, text: string) => text,
							bold: (text: string) => text,
						},
						{ matches: () => false },
						done,
					);
					nativeDone = done;
					controller.abort();
					nativeDone({ answers: ["late completion"] });
					queueMicrotask(() => void component);
					return promise;
				},
			},
		} as unknown as ExtensionContext;

		await expect(
			askInTui("Question", singleQuestion()[0]!, ctx, controller.signal),
		).resolves.toBeUndefined();
		expect(doneCalls).toBe(1);
	});
});

describe("runAskFlow in TUI mode", () => {
	const keys = Object.values(KEYS);

	it("selects an option with enter", async () => {
		const tui = tuiSession();
		const flow = __test.runAskFlow(singleQuestion(), tui.ctx);
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(KEYS["tui.select.confirm"]!);
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: { db: { answers: ["SQLite"] } },
		});
	});

	it("routes Other through the free-text input", async () => {
		const tui = tuiSession();
		const flow = __test.runAskFlow(singleQuestion(), tui.ctx);
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(KEYS["tui.select.confirm"]!);
		for (const key of ["C", "u", "s", "t", "o", "m", "\r"]) {
			tui.component()?.handleInput(key);
		}
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: { db: { answers: ["Custom"] } },
		});
	});

	it("attaches notes through tab and submits the highlighted option", async () => {
		const tui = tuiSession();
		const flow = __test.runAskFlow(singleQuestion(), tui.ctx);
		tui.component()?.handleInput(KEYS["tui.input.tab"]!);
		for (const key of ["l", "a", "t", "e", "r", "\r"]) {
			tui.component()?.handleInput(key);
		}
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: { db: { answers: ["Postgres (Recommended)"], notes: "later" } },
		});
	});

	it("wraps questions, options, and free-text input to the available width", async () => {
		const questions = __test.normalizeQuestions([
			{
				id: "wrap",
				question:
					"Which database should handle this unusually demanding workload?",
				options: [
					{
						label: "Postgres with replication (Recommended)",
						description: "Supports relational queries and resilient failover.",
					},
					{ label: "SQLite", description: "Embedded and deliberately simple." },
				],
			},
		]);
		const tui = tuiSession();
		const flow = __test.runAskFlow(questions, tui.ctx);
		const initial = tui.component()?.render(24) ?? [];
		expect(initial.every((line) => visibleWidth(line) <= 24)).toBe(true);
		expect(initial.join("\n")).toContain("demanding workload?");
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(KEYS["tui.select.confirm"]!);
		for (const key of "A free-form answer long enough to wrap") {
			tui.component()?.handleInput(key);
		}
		const withInput = tui.component()?.render(24) ?? [];
		expect(withInput.every((line) => visibleWidth(line) <= 24)).toBe(true);
		expect(
			withInput.filter(
				(line) => line.includes("free-form") || line.includes("enough to wrap"),
			),
		).toHaveLength(2);
		tui.component()?.handleInput("\r");
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: {
				wrap: { answers: ["A free-form answer long enough to wrap"] },
			},
		});
	});

	it("selects an option with the mouse in fullscreen TUI mode", async () => {
		const tui = tuiSession();
		const flow = __test.runAskFlow(singleQuestion(), tui.ctx);
		const lines = tui.component()?.render(80) ?? [];
		const sqliteRow = lines.findIndex((line) => line.includes("SQLite"));
		expect(sqliteRow).toBeGreaterThanOrEqual(0);
		tui.component()?.handleMouse?.(mouseEvent("press", sqliteRow));
		tui.component()?.handleMouse?.(mouseEvent("click", sqliteRow));
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: { db: { answers: ["SQLite"] } },
		});
	});

	it("cancels from the option list with escape", async () => {
		const tui = tuiSession();
		const flow = __test.runAskFlow(singleQuestion(), tui.ctx);
		tui.component()?.handleInput(KEYS["tui.select.cancel"]!);
		await expect(flow).resolves.toEqual({ status: "cancelled" });
	});

	it("toggles multi-select options with space", async () => {
		const questions = __test.normalizeQuestions([
			{
				id: "feat",
				question: "Which features?",
				multiSelect: true,
				options: [
					{ label: "Auth", description: "a" },
					{ label: "Audit", description: "b" },
				],
			},
		]);
		const tui = tuiSession();
		const flow = __test.runAskFlow(questions, tui.ctx);
		tui.component()?.handleInput(" ");
		tui.component()?.handleInput(KEYS["tui.select.down"]!);
		tui.component()?.handleInput(" ");
		const rendered = tui.component()?.render(80)?.join("\n") ?? "";
		tui.component()?.handleInput(KEYS["tui.select.confirm"]!);
		await expect(flow).resolves.toEqual({
			status: "answered",
			answers: { feat: { answers: ["Auth", "Audit"] } },
		});
		expect(rendered).toContain("Which features?");
		expect(rendered).toContain("Other");
		expect(keys).toContain(KEYS["tui.select.confirm"]);
	});
});