@selesai/code 0.13.13 → 0.13.14

package/dist/extensions/question/row-layout.ts

@@ -0,0 +1,165 @@
+// Single-select row layout (inlined from pi-ask-user/single-select-layout.ts).
+
+import { COMMENT_TOGGLE_LABEL, FREEFORM_LABEL } from "./constants.ts";
+import type { AnnotatedRow, ItemBlock, ListItem, QuestionOption, RenderRowsParams } from "./types.ts";
+
+export function wrapPlain(text: string, width: number): string[] {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!normalized) return [""];
+	if (width <= 1) return [...normalized];
+
+	const words = normalized.split(" ");
+	const lines: string[] = [];
+	let current = "";
+
+	for (const word of words) {
+		if (!current) {
+			if (word.length <= width) {
+				current = word;
+			} else {
+				for (let i = 0; i < word.length; i += width) lines.push(word.slice(i, i + width));
+			}
+			continue;
+		}
+		const candidate = `${current} ${word}`;
+		if (candidate.length <= width) {
+			current = candidate;
+			continue;
+		}
+		lines.push(current);
+		if (word.length <= width) {
+			current = word;
+		} else {
+			current = "";
+			for (let i = 0; i < word.length; i += width) {
+				const chunk = word.slice(i, i + width);
+				if (chunk.length === width || i + width < word.length) lines.push(chunk);
+				else current = chunk;
+			}
+		}
+	}
+	if (current) lines.push(current);
+	return lines;
+}
+
+export function padLine(prefix: string, content: string): string {
+	return `${prefix}${content}`.trimEnd();
+}
+
+export function buildItemBlocks(
+	options: QuestionOption[],
+	width: number,
+	allowFreeform: boolean,
+	allowComment: boolean,
+	commentEnabled: boolean,
+	selectedIndex: number,
+	hideDescriptions = false,
+): ItemBlock[] {
+	const normalizedWidth = Math.max(12, width);
+	const allItems: ListItem[] = options.map((option) => ({ type: "option", option }));
+	if (allowComment) {
+		allItems.push({
+			type: "comment-toggle",
+			option: { value: "__comment__", label: `${commentEnabled ? "[✓]" : "[ ]"} ${COMMENT_TOGGLE_LABEL}` },
+		});
+	}
+	if (allowFreeform) {
+		allItems.push({ type: "freeform", option: { value: "__other__", label: FREEFORM_LABEL } });
+	}
+
+	return allItems.map((item, itemIndex) => {
+		const pointer = itemIndex === selectedIndex ? "→" : " ";
+		const lines: string[] = [];
+
+		if (item.type === "comment-toggle" || item.type === "freeform") {
+			const prefix = `${pointer}   `;
+			const wrapped = wrapPlain(item.option.label, Math.max(8, normalizedWidth - prefix.length));
+			wrapped.forEach((line, lineIndex) => {
+				lines.push(padLine(lineIndex === 0 ? prefix : " ".repeat(prefix.length), line));
+			});
+			return { itemIndex, lines };
+		}
+
+		const numberPrefix = `${pointer} ${itemIndex + 1}. `;
+		const continuationPrefix = " ".repeat(numberPrefix.length);
+		const titleLines = wrapPlain(item.option.label, Math.max(8, normalizedWidth - numberPrefix.length));
+		titleLines.forEach((line, lineIndex) => {
+			lines.push(padLine(lineIndex === 0 ? numberPrefix : continuationPrefix, line));
+		});
+
+		if (item.option.description && !hideDescriptions) {
+			const descriptionPrefix = "      ";
+			const descriptionLines = wrapPlain(item.option.description, Math.max(8, normalizedWidth - descriptionPrefix.length));
+			descriptionLines.forEach((line) => {
+				lines.push(padLine(descriptionPrefix, line));
+			});
+		}
+
+		return { itemIndex, lines };
+	});
+}
+
+export function flattenBlocks(blocks: ItemBlock[], selectedIndex: number): AnnotatedRow[] {
+	return blocks.flatMap((block) =>
+		block.lines.map((line) => ({ line, selected: block.itemIndex === selectedIndex })),
+	);
+}
+
+export function renderSingleSelectRows({
+	options,
+	selectedIndex,
+	width,
+	allowFreeform,
+	allowComment = false,
+	commentEnabled = false,
+	maxRows,
+	hideDescriptions,
+}: RenderRowsParams): AnnotatedRow[] {
+	const itemCount = options.length + (allowComment ? 1 : 0) + (allowFreeform ? 1 : 0);
+	const blocks = buildItemBlocks(options, width, allowFreeform, allowComment, commentEnabled, selectedIndex, hideDescriptions);
+	const allRows = flattenBlocks(blocks, selectedIndex);
+
+	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
+		return allRows;
+	}
+
+	const safeMaxRows = Math.max(1, Math.floor(maxRows));
+	const selectedBlock = blocks[selectedIndex] ?? blocks[0];
+	// Blocks is never empty here: empty blocks means empty allRows, which is
+	// already returned by the allRows.length <= maxRows guard above.
+	/* v8 ignore next 1 */
+	if (!selectedBlock) return [];
+
+	const indicator = `  (${selectedIndex + 1}/${itemCount})`;
+	const availableRows = safeMaxRows > 1 ? safeMaxRows - 1 : 1;
+
+	if (selectedBlock.lines.length >= availableRows) {
+		const visible = selectedBlock.lines.slice(0, availableRows).map((line) => ({ line, selected: true }));
+		if (safeMaxRows > 1) visible.push({ line: indicator, selected: false });
+		return visible.slice(0, safeMaxRows);
+	}
+
+	let start = selectedIndex;
+	let end = selectedIndex + 1;
+	let usedRows = selectedBlock.lines.length;
+
+	while (true) {
+		const nextCanFit = end < blocks.length && usedRows + blocks[end]!.lines.length <= availableRows;
+		if (nextCanFit) {
+			usedRows += blocks[end]!.lines.length;
+			end += 1;
+			continue;
+		}
+		const prevCanFit = start > 0 && usedRows + blocks[start - 1]!.lines.length <= availableRows;
+		if (prevCanFit) {
+			start -= 1;
+			usedRows += blocks[start]!.lines.length;
+			continue;
+		}
+		break;
+	}
+
+	const visible = flattenBlocks(blocks.slice(start, end), selectedIndex);
+	visible.push({ line: indicator, selected: false });
+	return visible.slice(0, safeMaxRows);
+}

package/dist/extensions/question/schemas.ts

@@ -0,0 +1,43 @@
+// Strict, batch-first TypeBox schema for the question tool.
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+const OptionSchema = Type.Object({
+	value: Type.String({ description: "Stable machine value returned when selected" }),
+	label: Type.String({ description: "Human-readable option label" }),
+	description: Type.Optional(Type.String({ description: "Optional help text shown under the option" })),
+}, { additionalProperties: false });
+
+const QuestionBase = {
+	id: Type.Optional(Type.String({ description: "Unique answer id. Missing ids become q1, q2, and so on." })),
+	label: Type.Optional(Type.String({ description: "Short page label. Defaults to Q1, Q2, and so on." })),
+	question: Type.String({ description: "Question shown to the user" }),
+	context: Type.Optional(Type.String({ description: "Optional plain-text context shown before the question" })),
+};
+
+const SelectQuestionSchema = Type.Object({
+	...QuestionBase,
+	type: StringEnum(["select"] as const),
+	options: Type.Array(OptionSchema, { minItems: 1, description: "Available choices" }),
+	allowOther: Type.Optional(Type.Boolean({ description: "Allow a custom Other text answer (default: true)" })),
+}, { additionalProperties: false });
+
+const MultiSelectQuestionSchema = Type.Object({
+	...QuestionBase,
+	type: StringEnum(["multiselect"] as const),
+	options: Type.Array(OptionSchema, { minItems: 1, description: "Available choices" }),
+	allowOther: Type.Optional(Type.Boolean({ description: "Allow custom Other text alongside selected values (default: true)" })),
+}, { additionalProperties: false });
+
+const TextQuestionSchema = Type.Object({
+	...QuestionBase,
+	type: StringEnum(["text"] as const),
+}, { additionalProperties: false });
+
+export const QuestionParamsSchema = Type.Object({
+	questions: Type.Array(Type.Union([SelectQuestionSchema, MultiSelectQuestionSchema, TextQuestionSchema]), {
+		minItems: 1,
+		description: "One or more typed questions shown as a paged wizard followed by atomic review and submission.",
+	}),
+}, { additionalProperties: false });

package/dist/extensions/question/selection-mode.ts

@@ -0,0 +1,47 @@
+// SelectionMode strategy — isolates single-vs-multi selection behavior.
+
+import type { QuestionOption } from "./types.ts";
+
+export interface QuestionListState {
+	selectedIndex: number;
+	checked: ReadonlySet<number>;
+	options: QuestionOption[];
+}
+
+export interface SelectionMode {
+	readonly multi: boolean;
+	toggle(checked: Set<number>, index: number): void;
+	buildResult(state: QuestionListState): string[];
+	/** Returns whether to toggle (multi) or just select (single), and the new selectedIndex. */
+	handleNumberKey(idx: number, count: number): { toggle: boolean; selectIndex: number };
+}
+
+export const SingleSelect: SelectionMode = {
+	multi: false,
+	toggle() {},
+	buildResult(state) {
+		const value = state.options[state.selectedIndex]?.value;
+		return value ? [value] : [];
+	},
+	handleNumberKey(idx, count) {
+		return { toggle: false, selectIndex: Math.min(idx, count - 1) };
+	},
+};
+
+export const MultiSelect: SelectionMode = {
+	multi: true,
+	toggle(checked, index) {
+		if (index < 0) return;
+		if (checked.has(index)) checked.delete(index);
+		else checked.add(index);
+	},
+	buildResult(state) {
+		return Array.from(state.checked)
+			.sort((a, b) => a - b)
+			.map((i) => state.options[i]?.value)
+			.filter((value): value is string => !!value);
+	},
+	handleNumberKey(idx, count) {
+		return { toggle: true, selectIndex: Math.min(idx, count - 1) };
+	},
+};

package/dist/extensions/question/shortcuts.ts

@@ -0,0 +1,44 @@
+// Shortcut resolution for the optional-comment toggle key.
+
+import { matchesKey } from "@earendil-works/pi-tui";
+
+import { DEFAULT_COMMENT_TOGGLE_KEY, DISABLED_SHORTCUT, SHORTCUT_DISABLE_VALUES } from "./constants.ts";
+import type { ResolvedShortcut, ResolvedShortcuts } from "./types.ts";
+
+export function normalizeShortcutSpec(value: string | null | undefined): string | null | undefined {
+	if (value === undefined) return undefined;
+	if (value === null) return null;
+	const trimmed = value.trim().toLowerCase();
+	if (SHORTCUT_DISABLE_VALUES.has(trimmed)) return null;
+	return trimmed;
+}
+
+export function isValidShortcutSpec(spec: string): boolean {
+	if (!spec) return false;
+	if (!/^[a-z0-9+_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]+$/i.test(spec)) return false;
+	if (spec.startsWith("+") || spec.endsWith("+")) return false;
+	if (spec.includes("++")) return false;
+	return true;
+}
+
+export function buildShortcut(spec: string): ResolvedShortcut {
+	return { disabled: false, spec, matches: (data: string) => matchesKey(data, spec as any) };
+}
+
+export function resolveShortcut(
+	paramValue: string | null | undefined,
+	envValue: string | undefined,
+	defaultSpec: string,
+): ResolvedShortcut {
+	for (const raw of [paramValue, envValue, defaultSpec]) {
+		const normalized = normalizeShortcutSpec(raw);
+		if (normalized === undefined) continue;
+		if (normalized === null) return DISABLED_SHORTCUT;
+		if (isValidShortcutSpec(normalized)) return buildShortcut(normalized);
+	}
+	return DISABLED_SHORTCUT;
+}
+
+export function resolveShortcuts(commentToggleKey: string | null | undefined, commentEnv: string | undefined): ResolvedShortcuts {
+	return { commentToggle: resolveShortcut(commentToggleKey, commentEnv, DEFAULT_COMMENT_TOGGLE_KEY) };
+}

package/dist/extensions/question/tests/batch.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+
+import { buildQuestionAnswers, prepareQuestions, saveDraftQuestion } from "../batch.ts";
+import type { DraftQuestionState } from "../types.ts";
+
+describe("question batch helpers", () => {
+	it("prepareQuestions: normalizes typed questions and generated ids", () => {
+		const result = prepareQuestions([
+			{ type: "select", question: "Pick a color", options: [{ value: "red", label: "Red" }, { value: "blue", label: "Blue" }] },
+			{ type: "text", id: "notes", label: "Notes", question: "Anything else?" },
+		]);
+		expect("questions" in result).toBe(true);
+		if (!("questions" in result)) return;
+		expect(result.questions).toEqual([
+			{
+				id: "q1",
+				label: "Q1",
+				question: "Pick a color",
+				context: undefined,
+				type: "select",
+				options: [
+					{ value: "red", label: "Red", description: undefined },
+					{ value: "blue", label: "Blue", description: undefined },
+				],
+				allowOther: true,
+			},
+			{
+				id: "notes",
+				label: "Notes",
+				question: "Anything else?",
+				context: undefined,
+				type: "text",
+				options: [],
+				allowOther: false,
+			},
+		]);
+	});
+
+	it("prepareQuestions: rejects empty batches, generated-id collisions, and duplicate option values", () => {
+		expect(prepareQuestions([])).toEqual({ error: "questions must contain at least one question." });
+		expect((prepareQuestions([
+			{ type: "text", id: "q2", question: "One" },
+			{ type: "text", question: "Two" },
+		]) as { error: string }).error).toMatch(/duplicate id: q2/);
+		expect((prepareQuestions([{
+			type: "select",
+			question: "Choose",
+			options: [{ value: "same", label: "A" }, { value: "same", label: "B" }],
+		}]) as { error: string }).error).toMatch(/duplicate value: same/);
+	});
+
+	it("prepareQuestions: rejects missing question, bad type, empty options, and bad option fields", () => {
+		expect((prepareQuestions([{ type: "text" }]) as { error: string }).error).toMatch(/non-empty question/);
+		expect((prepareQuestions([{ type: "radio", question: "X", options: [{ value: "a", label: "A" }] }]) as { error: string }).error).toMatch(/type must be select, multiselect, or text/);
+		expect((prepareQuestions([{ type: "select", question: "X", options: [] }]) as { error: string }).error).toMatch(/at least one option/);
+		expect((prepareQuestions([{ type: "select", question: "X", options: [{ value: "", label: "A" }] }]) as { error: string }).error).toMatch(/value and label must be non-empty/);
+		expect((prepareQuestions([{ type: "select", question: "X", options: [{ value: "a", label: "" }] }]) as { error: string }).error).toMatch(/value and label must be non-empty/);
+	});
+
+	it("prepareQuestions: trims id/label/context and defaults allowOther", () => {
+		const result = prepareQuestions([
+			{ type: "multiselect", id: "  m1  ", label: "  Multi  ", question: "  Pick many  ", context: "  ctx  ", options: [{ value: "a", label: "A", description: "  desc  " }] },
+		]);
+		expect("questions" in result).toBe(true);
+		if (!("questions" in result)) return;
+		expect(result.questions[0]).toEqual({
+			id: "m1",
+			label: "Multi",
+			question: "Pick many",
+			context: "ctx",
+			type: "multiselect",
+			options: [{ value: "a", label: "A", description: "desc" }],
+			allowOther: true,
+		});
+	});
+
+	it("saveDraftQuestion: clearing an answer while navigating back leaves it unanswered", () => {
+		const states = new Map<string, DraftQuestionState>([["q1", { status: "answered", response: { kind: "text", text: "old" } }]]);
+		saveDraftQuestion(states, "q1", null, false);
+		expect(states.has("q1")).toBe(false);
+	});
+
+	it("saveDraftQuestion: blank answer with markBlankSkipped marks skipped", () => {
+		const states = new Map<string, DraftQuestionState>();
+		saveDraftQuestion(states, "q1", null, true);
+		expect(states.get("q1")).toEqual({ status: "skipped" });
+	});
+
+	it("saveDraftQuestion: response marks answered", () => {
+		const states = new Map<string, DraftQuestionState>();
+		saveDraftQuestion(states, "q1", { kind: "text", text: "answer" }, true);
+		expect(states.get("q1")).toEqual({ status: "answered", response: { kind: "text", text: "answer" } });
+	});
+
+	it("buildQuestionAnswers: preserves answered, skipped, and unvisited states", () => {
+		const prepared = prepareQuestions([
+			{ type: "text", id: "a", question: "A" },
+			{ type: "text", id: "b", question: "B" },
+			{ type: "text", id: "c", question: "C" },
+		]);
+		expect("questions" in prepared).toBe(true);
+		if (!("questions" in prepared)) return;
+		const states = new Map<string, DraftQuestionState>([
+			["a", { status: "answered", response: { kind: "text", text: "answer" } }],
+			["b", { status: "skipped" }],
+		]);
+		expect(buildQuestionAnswers(prepared.questions, states)).toEqual([
+			{ id: "a", status: "answered", response: { kind: "text", text: "answer" } },
+			{ id: "b", status: "skipped" },
+			{ id: "c", status: "unanswered" },
+		]);
+	});
+});

package/dist/extensions/question/tests/exp.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import questionExtension from "../index.ts";
+
+const theme = {
+	fg: (_name: string, value: string) => value,
+	bg: (_name: string, value: string) => value,
+	bold: (value: string) => value,
+};
+const tui = { requestRender() {}, terminal: { rows: 24 } };
+const keybindings = {
+	matches: (data: string, action: string) =>
+		(data === "\r" && action === "tui.select.confirm") ||
+		(data === "\x1b" && action === "tui.select.cancel"),
+	getKeys: () => ["Enter"],
+};
+
+async function runWizard(params: unknown) {
+	let tool: any;
+	let component: any;
+	let done!: (value: unknown) => void;
+	questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
+	const execution = tool.execute("call", params, undefined, undefined, {
+		mode: "tui",
+		ui: {
+			custom: (factory: (...args: any[]) => unknown) => new Promise((resolve) => {
+				done = resolve;
+				component = factory(tui, theme, keybindings, done);
+			}),
+		},
+	} as any);
+	return { component: () => component, execution };
+}
+
+describe("exp", () => {
+	it("text question focused=false", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "text", question: "Type" }],
+		});
+		component().focused = false;
+		component().focused = true;
+		component().focused = false;
+		component().handleInput("x");
+		component().handleInput("\r");
+		await execution;
+		expect(true).toBe(true);
+	});
+
+	it("multiselect empty confirm", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "multiselect", question: "Pick", options: [{ value: "a", label: "A" }] }],
+		});
+		component().handleInput("\r"); // empty confirm → no commit
+		component().handleInput(" ");
+		component().handleInput("\r"); // now commits
+		await execution;
+		expect(true).toBe(true);
+	});
+
+	it("text empty submit", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "text", question: "Type" }],
+		});
+		component().handleInput("\r"); // empty submit → no commit
+		component().handleInput("a");
+		component().handleInput("\r");
+		await execution;
+		expect(true).toBe(true);
+	});
+});

package/dist/extensions/question/tests/exp2.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import questionExtension from "../index.ts";
+
+const theme = {
+	fg: (_name: string, value: string) => value,
+	bg: (_name: string, value: string) => value,
+	bold: (value: string) => value,
+};
+const tui = { requestRender() {}, terminal: { rows: 24 } };
+const keybindings = {
+	matches: (data: string, action: string) =>
+		(data === "\r" && action === "tui.select.confirm") ||
+		(data === "\x1b" && action === "tui.select.cancel"),
+	getKeys: () => ["Enter"],
+};
+
+async function runWizard(params: unknown) {
+	let tool: any;
+	let component: any;
+	let done!: (value: unknown) => void;
+	questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
+	const execution = tool.execute("call", params, undefined, undefined, {
+		mode: "tui",
+		ui: {
+			custom: (factory: (...args: any[]) => unknown) => new Promise((resolve) => {
+				done = resolve;
+				component = factory(tui, theme, keybindings, done);
+			}),
+		},
+	} as any);
+	return { component: () => component, execution };
+}
+
+describe("exp2", () => {
+	it("text question construction only", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "text", question: "Type" }],
+		});
+		component().render(120);
+		component().handleInput("a");
+		component().handleInput("\r");
+		await execution;
+		expect(true).toBe(true);
+	});
+
+	it("blur then non-enter key", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "text", question: "Type" }],
+		});
+		component().handleInput("\x1b"); // blur
+		component().handleInput("x"); // non-enter while blurred
+		component().handleInput("\r"); // re-focus
+		component().handleInput("a");
+		component().handleInput("\r");
+		await execution;
+		expect(true).toBe(true);
+	});
+});

package/dist/extensions/question/tests/exp3.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import questionExtension from "../index.ts";
+
+const theme = {
+	fg: (_name: string, value: string) => value,
+	bg: (_name: string, value: string) => value,
+	bold: (value: string) => value,
+};
+const tui = { requestRender() {}, terminal: { rows: 24 } };
+const keybindings = {
+	matches: (data: string, action: string) =>
+		(data === "\r" && action === "tui.select.confirm") ||
+		(data === "\x1b" && action === "tui.select.cancel"),
+	getKeys: () => ["Enter"],
+};
+
+async function runWizard(params: unknown) {
+	let tool: any;
+	let component: any;
+	let done!: (value: unknown) => void;
+	questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
+	const execution = tool.execute("call", params, undefined, undefined, {
+		mode: "tui",
+		ui: {
+			custom: (factory: (...args: any[]) => unknown) => new Promise((resolve) => {
+				done = resolve;
+				component = factory(tui, theme, keybindings, done);
+			}),
+		},
+	} as any);
+	return { component: () => component, execution };
+}
+
+describe("exp3", () => {
+	it("focused true then false on text", async () => {
+		const { component, execution } = await runWizard({
+			questions: [{ type: "text", question: "Type" }],
+		});
+		component().focused = true; // editor.focused = true && true
+		component().focused = false; // editor.focused = false && true
+		component().handleInput("a");
+		component().handleInput("\r");
+		await execution;
+		expect(true).toBe(true);
+	});
+});

package/dist/extensions/question/tests/helpers.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	createSelectionResponse,
+	createTextResponse,
+	formatQuestionResponse,
+	formatResponseSummary,
+	formatOptionsForMessage,
+	oneLine,
+	previewText,
+	trimText,
+} from "../helpers.ts";
+import type { PreparedQuestion } from "../types.ts";
+
+describe("question helpers", () => {
+	it("trimText trims and returns undefined for blank", () => {
+		expect(trimText("  ")).toBeUndefined();
+		expect(trimText(undefined)).toBeUndefined();
+		expect(trimText(null)).toBeUndefined();
+		expect(trimText("  hello  ")).toBe("hello");
+	});
+
+	it("createTextResponse trims edges and rejects blank text", () => {
+		expect(createTextResponse("  ")).toBeNull();
+		expect(createTextResponse(undefined)).toBeNull();
+		expect(createTextResponse("  hello\nworld  ")).toEqual({ kind: "text", text: "hello\nworld" });
+	});
+
+	it("createSelectionResponse supports values plus Other and rejects empty", () => {
+		expect(createSelectionResponse([], "  ")).toBeNull();
+		expect(createSelectionResponse([], undefined)).toBeNull();
+		expect(createSelectionResponse([" a ", "b"], " other ")).toEqual({
+			kind: "selection",
+			values: ["a", "b"],
+			otherText: "other",
+		});
+		expect(createSelectionResponse(["a"], undefined)).toEqual({ kind: "selection", values: ["a"] });
+	});
+
+	it("formatResponseSummary returns machine values", () => {
+		expect(formatResponseSummary({ kind: "selection", values: ["a", "b"], otherText: "c" })).toBe("a, b, c");
+		expect(formatResponseSummary({ kind: "selection", values: ["a"] })).toBe("a");
+		expect(formatResponseSummary({ kind: "text", text: "hello" })).toBe("hello");
+	});
+
+	it("formatQuestionResponse maps stable values to labels", () => {
+		const question: PreparedQuestion = {
+			id: "q1",
+			label: "Q1",
+			question: "Pick",
+			type: "multiselect",
+			options: [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta" }],
+			allowOther: true,
+		};
+		expect(formatQuestionResponse(question, { kind: "selection", values: ["b"], otherText: "Gamma" })).toBe("Beta, Other: Gamma");
+		expect(formatQuestionResponse(question, { kind: "selection", values: ["unknown"] })).toBe("unknown");
+		expect(formatQuestionResponse(question, { kind: "text", text: "plain" })).toBe("plain");
+	});
+
+	it("formatOptionsForMessage numbers options with descriptions", () => {
+		expect(formatOptionsForMessage([
+			{ value: "a", label: "Alpha" },
+			{ value: "b", label: "Beta", description: "the beta" },
+		])).toBe("1. Alpha\n2. Beta — the beta");
+	});
+
+	it("previewText bounds multiline summaries", () => {
+		expect(previewText("one\ntwo\nthree", 160, 2)).toBe("one\ntwo…");
+		expect(previewText("a".repeat(200), 10, 2)).toBe(`${"a".repeat(9)}…`);
+		expect(previewText("short", 160, 2)).toBe("short");
+		expect(previewText("", 160, 2)).toBe("");
+	});
+
+	it("oneLine collapses whitespace and truncates", () => {
+		expect(oneLine("  hello   world  ")).toBe("hello world");
+		expect(oneLine("a".repeat(20), 10)).toBe(`${"a".repeat(9)}…`);
+		expect(oneLine(undefined)).toBe("");
+		expect(oneLine(42)).toBe("42");
+	});
+
+	it("previewText handles single-line and exact-boundary text", () => {
+		expect(previewText("one line", 160, 2)).toBe("one line");
+		expect(previewText("a".repeat(10), 10, 2)).toBe("a".repeat(10));
+		expect(previewText("a".repeat(11), 10, 2)).toBe(`${"a".repeat(9)}…`);
+	});
+
+	it("previewText handles nullish values", () => {
+		expect(previewText(null)).toBe("");
+		expect(previewText(undefined)).toBe("");
+		expect(previewText(null, 10, 1)).toBe("");
+		expect(previewText(undefined, 10, 1)).toBe("");
+	});
+});