@zhushanwen/pi-ask-user 0.0.1

package/src/__tests__/e2e-harness.ts

@@ -0,0 +1,95 @@
+// src/__tests__/e2e-harness.ts
+// E2E test harness for ask_user. Drives tool.execute() end-to-end with a
+// REAL AskUserComponent and simulated key sequences — no mocking of internal
+// state. Mocks only the Pi surface (registerTool, getAllTools, setActiveTools,
+// ctx.ui.custom) since those are the only host-API touch points.
+
+import { AskUserComponent } from "../component";
+import factory from "../index";
+import type { AskUserDetails, Question, Result } from "../types";
+import { mockTui, stubTheme } from "./fixtures";
+
+/** Subset of Pi that ask_user's factory touches. */
+interface PiShape {
+	activeTools: string[] | null;
+	tool: unknown;
+	registerTool(t: unknown): void;
+	getAllTools(): { name: string }[];
+	setActiveTools(names: string[]): void;
+}
+
+export interface E2EApi {
+	/** Most recent execute() result. Populated after getExecuted() resolves. */
+	keys(seq: string[]): void;
+	abort(): void;
+	getExecuted(): Promise<AskUserDetails>;
+	pi: { activeTools: string[] | null };
+}
+
+export interface E2EOptions {
+	hasUI?: boolean;
+	preAborted?: boolean;
+}
+
+export function makeE2E(questions: Question[], opts: E2EOptions = {}): E2EApi {
+	const { hasUI = true, preAborted = false } = opts;
+	const controller = new AbortController();
+	if (preAborted) controller.abort();
+
+	const pi: PiShape = {
+		activeTools: null,
+		tool: undefined,
+		registerTool(t) {
+			this.tool = t;
+		},
+		getAllTools() {
+			return [{ name: "ask_user" }, { name: "read" }, { name: "bash" }];
+		},
+		setActiveTools(names) {
+			this.activeTools = names;
+		},
+	};
+
+	factory(pi as never);
+
+	type Tool = {
+		execute(
+			toolCallId: string,
+			params: unknown,
+			signal: AbortSignal | undefined,
+			onUpdate: unknown,
+			ctx: unknown,
+		): Promise<AskUserDetails>;
+	};
+	const tool = pi.tool as Tool;
+	if (!tool) throw new Error("factory did not register a tool");
+
+	let compRef: AskUserComponent | null = null;
+
+	const execPromise = tool.execute(
+		"id",
+		{ questions },
+		controller.signal,
+		undefined,
+		{
+			hasUI,
+			signal: controller.signal,
+			ui: {
+				custom: <T = Result | null>(factoryFn: (...args: unknown[]) => unknown): Promise<T> =>
+					new Promise<T>((resolve) => {
+						const done = (r: T): void => resolve(r);
+						compRef = factoryFn(mockTui, stubTheme, {}, done) as AskUserComponent;
+					}),
+			},
+		},
+	);
+
+	return {
+		keys: (seq) => {
+			for (const k of seq) compRef?.handleInput(k);
+		},
+		abort: () => controller.abort(),
+		getExecuted: () => execPromise,
+		pi: { get activeTools() { return pi.activeTools; } },
+	};
+}

package/src/__tests__/e2e.test.ts

@@ -0,0 +1,184 @@
+// src/__tests__/e2e.test.ts
+// E2E test cases for ask_user. Drives tool.execute() → real AskUserComponent
+// → simulated keypresses → asserts on final execute() result contract.
+// Spec: .xyz-harness/2026-06-15-ask-user/e2e-test-cases.md
+
+import { describe, expect, it } from "vitest";
+
+import { makeE2E } from "./e2e-harness";
+
+// ── E2E-1: 单问题无评论 — 选第二项提交 ─────────────────
+describe("E2E-1: single question, no comment — pick 2nd option", () => {
+	const questions = [
+		{
+			question: "Which DB?",
+			options: [{ label: "Postgres" }, { label: "SQLite" }],
+		},
+	];
+
+	it("selects SQLite on ↓ + Enter and returns answers", async () => {
+		const e = makeE2E(questions);
+		e.keys(["\x1b[B", "\r"]); // ↓ + Enter
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		// User-facing summary
+		expect(result.content[0].text).toContain("Which DB?");
+		expect(result.content[0].text).toContain("SQLite");
+		// Data contract
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Which DB?"]).toBe("SQLite");
+		expect(details.questions.length).toBe(1);
+	});
+});
+
+// ── E2E-2: 单问题 + allowComment — 选项 + 评论拼接 ─────
+describe("E2E-2: single question + allowComment — option + comment joined", () => {
+	const questions = [
+		{
+			question: "Which DB?",
+			allowComment: true,
+			options: [{ label: "Postgres" }, { label: "SQLite" }],
+		},
+	];
+
+	it("joins selected option with comment via ' — '", async () => {
+		const e = makeE2E(questions);
+		// Enter 选 Postgres → 进评论模式 → 输 "fast" → Enter 保存（allowComment 分支）
+		e.keys(["\r", "f", "a", "s", "t", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Which DB?"]).toBe("Postgres — fast");
+		expect(result.content[0].text).toContain("Postgres — fast");
+	});
+});
+
+// ── E2E-3: 单问题 + allowComment — Enter 空评论跳过 ─────
+describe("E2E-3: single question + allowComment — Enter in comment skips", () => {
+	const questions = [
+		{
+			question: "Which DB?",
+			allowComment: true,
+			options: [{ label: "Postgres" }, { label: "SQLite" }],
+		},
+	];
+
+	it("empty Enter in comment mode keeps option without ' — ' suffix", async () => {
+		const e = makeE2E(questions);
+		// Enter 选 Postgres → 直接 Enter 评论模式跳过（AC-12）
+		e.keys(["\r", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		// 不含 " — " 分隔符
+		expect(details.answers["Which DB?"]).toBe("Postgres");
+			expect(details.answers["Which DB?"]).not.toContain("—");
+		});
+	});
+
+// ── E2E-4: 多问题提交 — 逐题选择后 Submit tab 提交（S-11）──────
+describe("E2E-4: multi-question submit — answer each then Submit tab", () => {
+	const questions = [
+		{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
+		{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
+	];
+
+	it("answers both via Enter + Enter on Submit tab", async () => {
+		const e = makeE2E(questions);
+		// Q1: Enter 选 A（auto-confirm → advance 到 Q2）
+		// Q2: Enter 选 X（auto-confirm → advance 到 Submit tab）
+		// Submit: Enter（allConfirmed）→ 提交
+		e.keys(["\r", "\r", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Q1"]).toBe("A");
+		expect(details.answers["Q2"]).toBe("X");
+		expect(result.content[0].text).toContain("Q1");
+		expect(result.content[0].text).toContain("Q2");
+	});
+});
+
+// ── E2E-5: 多选 — Space 勾选多项后 Enter 提交（S-11）──────────
+describe("E2E-5: multi-select — Space toggle two options then Enter", () => {
+	const questions = [
+		{
+			question: "Which features?",
+			multiSelect: true,
+			options: [{ label: "Auth" }, { label: "Search" }],
+		},
+	];
+
+	it("toggles Auth + Search via Space and submits on Enter", async () => {
+		const e = makeE2E(questions);
+		// Space 选 Auth（cursor@0）→ ↓ → Space 选 Search（cursor@1）→ Enter 确认（单问题→submit）
+		e.keys([" ", "\x1b[B", " ", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Which features?"]).toBe("Auth, Search");
+	});
+});
+
+// ── E2E-6: Other 自由文本 — 输入自定义答案（S-11）─────────────
+describe("E2E-6: Other free-text — type custom answer", () => {
+	const questions = [
+		{ question: "Which DB?", options: [{ label: "Postgres" }, { label: "SQLite" }] },
+	];
+
+	it("navigates to Other, types a custom answer, submits", async () => {
+		const e = makeE2E(questions);
+		// ↓↓ 到 Other（cursor@2，2 个普通选项 + Other）→ Enter 开 freeform 编辑器
+		// → 输 "redis" → Enter 保存（afterConfirm → advance → submit）
+		e.keys(["\x1b[B", "\x1b[B", "\r", "r", "e", "d", "i", "s", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Which DB?"]).toBe("redis");
+	});
+});
+
+// ── E2E-7: 取消 — Esc 进入确认层 → Esc 确认取消（S-11）────────
+describe("E2E-7: cancel — Esc confirm overlay → Esc cancels", () => {
+	const questions = [
+		{ question: "Which DB?", options: [{ label: "Postgres" }, { label: "SQLite" }] },
+	];
+
+	it("single Esc raises confirm overlay, second Esc confirms cancel", async () => {
+		const e = makeE2E(questions);
+		// 单问题首个 tab：Esc → pendingCancel 覆盖层；再 Esc → cancel() → done(null)
+		e.keys(["\x1b", "\x1b"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(true);
+		expect(result.content[0].text).toContain("cancelled");
+		// 取消时 answers 为空对象
+		expect(Object.keys(details.answers)).toHaveLength(0);
+	});
+});
+
+// ── E2E-8: cancel 在多问题场景 — 首个问题 Esc→Esc 取消（S-11 cancel 多问题路径）─
+describe("E2E-8: cancel during multi-question — Esc overlay then confirm", () => {
+	const questions = [
+		{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
+		{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
+	];
+
+	it("Esc on first question raises overlay, second Esc cancels all", async () => {
+		const e = makeE2E(questions);
+		e.keys(["\x1b", "\x1b"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(true);
+		// 取消返回 details.answers = {}，details.questions 仍回传（renderResult 数据源）
+		expect(Object.keys(details.answers)).toHaveLength(0);
+	});
+});

package/src/__tests__/fixtures.ts

@@ -0,0 +1,68 @@
+// src/__tests__/fixtures.ts
+// Shared test fixtures — stub theme, mock TUI, sample questions, key sequences.
+import type { Question, ThemeLike } from "../types";
+
+// ── Stub theme (passthrough — no ANSI codes, plain text) ──
+export const stubTheme: ThemeLike = {
+	fg: (_t: string, s: string) => s,
+	bg: (_t: string, s: string) => s,
+	bold: (s: string) => s,
+};
+
+// ── Mock TUI (no-op requestRender) ──
+export const mockTui = { requestRender: (): void => {} };
+
+// ── Key sequences (real terminal escape codes that matchesKey recognizes) ──
+export const ENTER = "\r";
+export const SPACE = " ";
+export const ESC = "\x1b";
+export const UP = "\x1b[A";
+export const DOWN = "\x1b[B";
+export const RIGHT = "\x1b[C";
+export const LEFT = "\x1b[D";
+export const TAB = "\t";
+export const BKSP = "\x7f";
+
+// ── Sample questions ──
+export const singleQ: Question = {
+	question: "Which DB?",
+	options: [
+		{ label: "Postgres", description: "Battle-tested" },
+		{ label: "SQLite", description: "Embedded" },
+	],
+};
+
+export const singleQWithComment: Question = {
+	question: "Which DB? (with comment)",
+	allowComment: true,
+	options: [
+		{ label: "Postgres", description: "Battle-tested" },
+		{ label: "SQLite", description: "Embedded" },
+	],
+};
+
+export const singleQMulti: Question = {
+	question: "Which features?",
+	multiSelect: true,
+	allowComment: true,
+	options: [
+		{ label: "Auth", description: "OAuth + session" },
+		{ label: "Search", description: "Full-text" },
+	],
+};
+
+export const multiQ: Question[] = [
+	{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
+	{
+		question: "Q2",
+		header: "Second",
+		options: [{ label: "X" }, { label: "Y" }],
+		multiSelect: true,
+	},
+	{ question: "Q3", header: "Third", options: [{ label: "M" }, { label: "N" }] },
+];
+
+export const multiQWithComment: Question[] = [
+	{ question: "Q1", header: "First", allowComment: true, options: [{ label: "A" }, { label: "B" }] },
+	{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
+];