@zhushanwen/pi-ask-user 0.1.0 → 1.0.0

package/src/__tests__/editor-ops.test.ts

@@ -0,0 +1,179 @@
+// src/__tests__/editor-ops.test.ts
+//
+// editor-ops.ts 独立单元测试。
+// 覆盖审查 S5 发现的 surrogate pair 边界盲区：
+//   - moveCursorLeft/Right 在 emoji（surrogate pair）边界正确按 code point 移动
+//   - deleteCharBeforeCursor 删整个 emoji code point
+//
+// 之前仅靠 component.test.ts 黑盒间接覆盖，无法直接锁定 surrogate 行为。
+
+import { describe, expect, it } from "vitest";
+
+import {
+	deleteCharBeforeCursor,
+	handleEditorPaste,
+	insertAtCursor,
+	moveCursorEnd,
+	moveCursorHome,
+	moveCursorLeft,
+	moveCursorRight,
+} from "../editor-ops.js";
+import { createQuestionState, type QuestionState } from "../types.js";
+
+function stateWith(text: string, cursor = text.length): QuestionState {
+	const s = createQuestionState();
+	s.draftText = text;
+	s.cursorIndex = cursor;
+	return s;
+}
+
+describe("moveCursorLeft", () => {
+	it("moves left by 1 for ASCII", () => {
+		const s = stateWith("abc", 3);
+		moveCursorLeft(s);
+		expect(s.cursorIndex).toBe(2);
+	});
+
+	it("moves left by 1 code point (2 UTF-16 units) for emoji", () => {
+		// "a😀b" → length=4 (a=1, 😀=2, b=1)，光标在末尾(4)
+		const s = stateWith("a😀b", 4);
+		moveCursorLeft(s); // 从 4 → 跳过 b 到 3
+		expect(s.cursorIndex).toBe(3);
+		moveCursorLeft(s); // 从 3 → 跳过 emoji 到 1（不是 2）
+		expect(s.cursorIndex).toBe(1);
+	});
+
+	it("does not go below 0", () => {
+		const s = stateWith("abc", 0);
+		moveCursorLeft(s);
+		expect(s.cursorIndex).toBe(0);
+	});
+
+	it("stops at 0 after emoji", () => {
+		const s = stateWith("😀", 2);
+		moveCursorLeft(s);
+		expect(s.cursorIndex).toBe(0);
+	});
+});
+
+describe("moveCursorRight", () => {
+	it("moves right by 1 for ASCII", () => {
+		const s = stateWith("abc", 0);
+		moveCursorRight(s);
+		expect(s.cursorIndex).toBe(1);
+	});
+
+	it("moves right by 1 code point (2 UTF-16 units) for emoji", () => {
+		// "a😀b" → 光标在 0，右移应到 1（a），再到 3（跳过 emoji 的 2 个 unit）
+		const s = stateWith("a😀b", 0);
+		moveCursorRight(s); // 0 → 1
+		expect(s.cursorIndex).toBe(1);
+		moveCursorRight(s); // 1 → 3（跳过 😀 的 2 个 unit）
+		expect(s.cursorIndex).toBe(3);
+	});
+
+	it("does not exceed draftText.length", () => {
+		const s = stateWith("ab", 2);
+		moveCursorRight(s);
+		expect(s.cursorIndex).toBe(2);
+	});
+
+	it("stops at end after emoji", () => {
+		const s = stateWith("x😀", 1);
+		moveCursorRight(s);
+		expect(s.cursorIndex).toBe(3); // 跳到末尾
+		moveCursorRight(s); // 不超出
+		expect(s.cursorIndex).toBe(3);
+	});
+});
+
+describe("deleteCharBeforeCursor", () => {
+	it("deletes single ASCII char", () => {
+		const s = stateWith("abc", 2);
+		const changed = deleteCharBeforeCursor(s);
+		expect(changed).toBe(true);
+		expect(s.draftText).toBe("ac");
+		expect(s.cursorIndex).toBe(1);
+	});
+
+	it("deletes entire emoji code point (2 UTF-16 units)", () => {
+		// "a😀b" 光标在 4（末尾），删除应删掉 b → "a😀"
+		const s = stateWith("a😀b", 4);
+		deleteCharBeforeCursor(s);
+		expect(s.draftText).toBe("a😀");
+		expect(s.cursorIndex).toBe(3);
+		// 再删一次应删掉整个 emoji（2 units），不是只删 1
+		deleteCharBeforeCursor(s);
+		expect(s.draftText).toBe("a");
+		expect(s.cursorIndex).toBe(1);
+	});
+
+	it("returns false at cursor 0 (nothing to delete)", () => {
+		const s = stateWith("abc", 0);
+		const changed = deleteCharBeforeCursor(s);
+		expect(changed).toBe(false);
+		expect(s.draftText).toBe("abc");
+		expect(s.cursorIndex).toBe(0);
+	});
+
+	it("deletes emoji at start of text", () => {
+		const s = stateWith("😀hello", 2);
+		deleteCharBeforeCursor(s);
+		expect(s.draftText).toBe("hello");
+		expect(s.cursorIndex).toBe(0);
+	});
+});
+
+describe("insertAtCursor", () => {
+	it("inserts text at cursor position", () => {
+		const s = stateWith("abc", 1);
+		insertAtCursor(s, "X");
+		expect(s.draftText).toBe("aXbc");
+		expect(s.cursorIndex).toBe(2);
+	});
+});
+
+describe("moveCursorHome / moveCursorEnd", () => {
+	it("home sets cursor to 0", () => {
+		const s = stateWith("abc", 2);
+		moveCursorHome(s);
+		expect(s.cursorIndex).toBe(0);
+	});
+
+	it("end sets cursor to draftText.length", () => {
+		const s = stateWith("a😀b", 0);
+		moveCursorEnd(s);
+		expect(s.cursorIndex).toBe(4);
+	});
+});
+
+describe("handleEditorPaste", () => {
+	it("inserts printable text", () => {
+		const s = stateWith("ab", 1);
+		const changed = handleEditorPaste(s, "XY");
+		expect(changed).toBe(true);
+		expect(s.draftText).toBe("aXYb");
+		expect(s.cursorIndex).toBe(3);
+	});
+
+	it("inserts emoji correctly (surrogate pair via Array.from)", () => {
+		const s = stateWith("", 0);
+		handleEditorPaste(s, "😀");
+		expect(s.draftText).toBe("😀");
+		expect(s.cursorIndex).toBe(2);
+	});
+
+	it("rejects unknown escape sequences (non-bracketed)", () => {
+		const s = stateWith("ab", 1);
+		const changed = handleEditorPaste(s, "\x1b[6n");
+		expect(changed).toBe(false);
+		expect(s.draftText).toBe("ab");
+	});
+
+	it("strips bracketed paste markers", () => {
+		const s = stateWith("", 0);
+		const changed = handleEditorPaste(s, "\x1b[200~hello\x1b[201~");
+		expect(changed).toBe(true);
+		expect(s.draftText).toBe("hello");
+	});
+});

package/src/__tests__/index.test.ts

@@ -6,6 +6,8 @@ import factory from "../index";
 import { mockTui, stubTheme } from "./fixtures";
 
 // ── Types for the registered tool ───────────────────────
+type TestMode = "tui" | "rpc" | "json" | "print";
+
 interface RegisteredTool {
 	name: string;
 	label: string;
@@ -16,6 +18,7 @@ interface RegisteredTool {
 		signal: AbortSignal | undefined,
 		onUpdate: unknown,
 		ctx: {
+			mode: TestMode;
 			hasUI: boolean;
 			signal?: AbortSignal;
 			ui: {
@@ -23,6 +26,11 @@ interface RegisteredTool {
 					factory: (...args: unknown[]) => unknown,
 					options?: { overlay?: boolean },
 				): Promise<T>;
+				select?: (
+					title: string,
+					options: string[],
+					opts?: { signal?: AbortSignal },
+				) => Promise<string | undefined>;
 			};
 		},
 	) => Promise<Record<string, unknown>>;
@@ -36,6 +44,9 @@ interface MockPi {
 	getAllTools(): { name: string }[];
 	activeTools?: string[] | null;
 	setActiveTools(names: string[]): void;
+	// session_start handler：factory 注册 ask_user channel handler 时调用（透传功能）。
+	// 测试不验证透传，提供空 on 让 factory 不抛错。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 /** Runs the factory, returns the captured registered tool. */
@@ -50,6 +61,10 @@ const getTool = (overrides: Partial<MockPi> = {}): RegisteredTool => {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler 注册透传 channel（subagent-workflow 可选），
+			// 测试不覆盖透传路径
+		},
 		...overrides,
 	};
 	factory(pi as never);
@@ -57,16 +72,40 @@ const getTool = (overrides: Partial<MockPi> = {}): RegisteredTool => {
 	return pi.tool;
 };
 
+// 真 headless ctx：mode='print'（无 dialog 能力，hasUI=false），ui 上无 select。
+// isGuiCapable(ctx)=false（mode≠'rpc'）→ 不走 RPC 分支 → custom 也不可用 → catch 走禁用。
+const makeHeadlessCtx = () => ({
+	mode: "print" as const,
+	hasUI: false,
+	signal: undefined as AbortSignal | undefined,
+	ui: {},
+});
+
 // ── Mock ctx builder ────────────────────────────────────
+// mode 区分三场景：'tui'（默认，走 custom）/ 'rpc'（走 select）/ 'print'（headless）。
+// Pi 的 hasUI：TUI 和 RPC 都为 true（dialog-capable），print/json 为 false。
+// RPC 模式才挂 select（与真实 Pi 一致：TUI 模式的 ctx.ui 不一定有 select）。
 const makeCtx = (
 	overrides: Partial<{
-		hasUI: boolean;
+		mode: TestMode;
 		customResult: unknown;
 		customThrows: Error | null;
+		selectResult: string | undefined;
+		selectThrows: Error | null;
 	}> = {},
 ) => {
-	const { hasUI = true, customResult = null, customThrows = null } = overrides;
+	const {
+		mode = "tui",
+		customResult = null,
+		customThrows = null,
+		selectResult = undefined,
+		selectThrows = null,
+	} = overrides;
+	const hasUI = mode === "tui" || mode === "rpc";
+	// RPC 模式才挂 select（与真实 Pi 一致：TUI 模式的 ctx.ui 不一定有 select）
+	const hasSelect = mode === "rpc";
 	return {
+		mode,
 		hasUI,
 		signal: undefined as AbortSignal | undefined,
 		ui: {
@@ -74,6 +113,18 @@ const makeCtx = (
 				if (customThrows) throw customThrows;
 				return customResult as T;
 			},
+			...(hasSelect
+				? {
+						select: async (
+							_title: string,
+							_options: string[],
+							_opts?: { signal?: AbortSignal },
+						): Promise<string | undefined> => {
+							if (selectThrows) throw selectThrows;
+							return selectResult;
+						},
+					}
+				: {}),
 		},
 	};
 };
@@ -156,45 +207,32 @@ describe("execute — validation (FR-2 / AC-8 / AC-13)", () => {
 });
 
 // ── I-5 ~ I-7: Headless（FR-8 / AC-7）──────────────────
+// 真 headless：hasUI=false 且 ui 上无 select（print 模式），askUserInteract 抛错 → 禁用工具。
 describe("execute — headless (FR-8 / AC-7)", () => {
-	it("I-5: hasUI=false → isError with interactive-session message", async () => {
+	it("I-5: headless (no select) → isError with disabled message", async () => {
 		const tool = getTool();
-		const result = await tool.execute("id", validSingle, undefined, undefined, makeCtx({ hasUI: false }));
+		const result = await tool.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
 		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("interactive");
+		expect(result.content[0].text).toContain("disabled");
 	});
 
-	it("I-6: hasUI=false disables ask_user tool via setActiveTools", async () => {
-		const tool = getTool();
-		await tool.execute("id", validSingle, undefined, undefined, makeCtx({ hasUI: false }));
-		// The mock setActiveTools stores into activeTools; getAllTools returns ask_user + other_tool.
-		// We verify by checking the pi mock captured a filtered list.
-		// Re-run with a pi that records the call.
+	it("I-6: headless disables ask_user tool via setActiveTools", async () => {
 		let captured: string[] | null = null;
-		const pi = {
-			registerTool() {},
-			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
-			setActiveTools: (names: string[]) => {
-				captured = names;
-			},
-		};
-		factory(pi as never);
-		// Re-extract tool — factory already registered, but registerTool is no-op above.
-		// Use the getTool approach with override instead:
 		const tool2 = getTool({
 			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
 			setActiveTools: (names: string[]) => {
 				captured = names;
 			},
 		});
-		await tool2.execute("id", validSingle, undefined, undefined, makeCtx({ hasUI: false }));
+		await tool2.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
 		expect(captured).not.toContain("ask_user");
 		expect(captured).toContain("other");
 	});
 
-	it("I-7: hasUI=false details.cancelled = true", async () => {
+	it("I-7: headless details.cancelled = true", async () => {
 		const tool = getTool();
-		const result = await tool.execute("id", validSingle, undefined, undefined, makeCtx({ hasUI: false }));
+		const result = await tool.execute("id", validSingle, undefined, undefined, makeHeadlessCtx());
+		// headless 走 step 2 提前返回：cancelled Result（禁用工具，不进交互分支）
 		expect(result.details.cancelled).toBe(true);
 	});
 });
@@ -221,6 +259,7 @@ describe("execute — signal abort (FR-10 / AC-14)", () => {
 		// 此前 mock 直接返回 customResult、从不调用 factory，该 abort 监听器是 dead path。
 		// 现在中断后监听器调用 done(null)，custom 解析为 null → cancelled。
 		const ctx = {
+			mode: "tui" as const,
 			hasUI: true,
 			signal: controller.signal,
 			ui: {
@@ -486,6 +525,7 @@ describe("execute — inline render (FR-3)", () => {
 		const tool = getTool();
 		let customArgCount = -1;
 		const ctx = {
+			mode: "tui" as const,
 			hasUI: true,
 			signal: undefined as AbortSignal | undefined,
 			ui: {
@@ -500,3 +540,251 @@ describe("execute — inline render (FR-3)", () => {
 		expect(customArgCount).toBe(1);
 	});
 });
+
+// ── RPC 模式（xyz-agent GUI 富交互协议）──────────────────
+// hasUI=false + ui.select 存在 → 走 askUserInteract（select 通道 + ASK_USER_MARKER）。
+// select 的返回值是前端 JSON.stringify 的 AskUserAnswers，index.ts 做格式转换。
+describe("execute — RPC mode (askUserInteract via select channel)", () => {
+	it("R-1: single-select answer → converted to Result.answers (key=question)", async () => {
+		const tool = getTool();
+		// 协议 answers：key=header（单问题无 header → question 全文），value=选中 label
+		const protoAnswers = JSON.stringify({ "Which DB?": "Postgres" });
+		const result = await tool.execute(
+			"id",
+			validSingle,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		expect(result.details.cancelled).toBe(false);
+		expect(result.details.answers["Which DB?"]).toBe("Postgres");
+		expect(result.content[0].text).toContain("Postgres");
+	});
+
+	it("R-2: multi-select answer (JSON array) → comma-joined labels", async () => {
+		const tool = getTool();
+		const multi = {
+			questions: [
+				{
+					question: "Which tools?",
+					header: "Tools",
+					options: [{ label: "A" }, { label: "B" }, { label: "C" }],
+					multiSelect: true,
+				},
+			],
+		};
+		// 协议多选：value = JSON.stringify(["A","C"])
+		const protoAnswers = JSON.stringify({ Tools: JSON.stringify(["A", "C"]) });
+		const result = await tool.execute(
+			"id",
+			multi,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		expect(result.details.answers["Which tools?"]).toBe("A, C");
+	});
+
+	it("R-2b: multi-select 乱序回传 → 按 options 定义顺序排序（S#3）", async () => {
+		const tool = getTool();
+		const multi = {
+			questions: [
+				{
+					question: "Which tools?",
+					header: "Tools",
+					options: [{ label: "A" }, { label: "B" }, { label: "C" }],
+					multiSelect: true,
+				},
+			],
+		};
+		// 前端回传顺序 ["C", "A"] —— 应按 options 索引重排为 "A, C"
+		const protoAnswers = JSON.stringify({ Tools: JSON.stringify(["C", "A"]) });
+		const result = await tool.execute(
+			"id",
+			multi,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		expect(result.details.answers["Which tools?"]).toBe("A, C");
+	});
+
+	it("R-3: Other free text → appended to answer parts", async () => {
+		const tool = getTool();
+		// 单选 Postgres + Other "Custom DB"
+		const protoAnswers = JSON.stringify({
+			"Which DB?": "Postgres",
+			"Which DB?__other": "Custom DB",
+		});
+		const result = await tool.execute(
+			"id",
+			validSingle,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		// TUI 语义：parts = [selected, other].join(", ")
+		expect(result.details.answers["Which DB?"]).toBe("Postgres, Custom DB");
+	});
+
+	it("R-4: comment → inlined with ' — ' separator", async () => {
+		const tool = getTool();
+		const withComment = {
+			questions: [
+				{
+					question: "Which DB?",
+					options: [{ label: "Postgres" }, { label: "SQLite" }],
+					allowComment: true,
+				},
+			],
+		};
+		const protoAnswers = JSON.stringify({
+			"Which DB?": "Postgres",
+			"Which DB?__comment": "prod constraint",
+		});
+		const result = await tool.execute(
+			"id",
+			withComment,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		expect(result.details.answers["Which DB?"]).toBe("Postgres — prod constraint");
+	});
+
+	it("R-5: user cancel (select returns undefined) → cancelled details", async () => {
+		const tool = getTool();
+		const result = await tool.execute(
+			"id",
+			validSingle,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: undefined }),
+		);
+		expect(result.content[0].text).toContain("User cancelled");
+		expect(result.details.cancelled).toBe(true);
+	});
+
+	it("R-6: select throws → isError + disabled (not retriable)", async () => {
+		const tool = getTool();
+		const result = await tool.execute(
+			"id",
+			validSingle,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectThrows: new Error("channel broken") }),
+		);
+		expect(result.isError).toBe(true);
+		expect(result.content[0].text).toContain("disabled");
+		expect(result.details.error).toBe("channel broken");
+	});
+
+	it("R-7: header used as answers key when provided", async () => {
+		const tool = getTool();
+		const multiQ = {
+			questions: [
+				{
+					question: "Which database?",
+					header: "DB",
+					options: [{ label: "Postgres" }, { label: "MySQL" }],
+				},
+			],
+		};
+		// 协议 answers key = header（"DB"），但 Result.answers key = question 全文
+		const protoAnswers = JSON.stringify({ DB: "Postgres" });
+		const result = await tool.execute(
+			"id",
+			multiQ,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		// 转换后 key 必须是 question 全文（与 TUI 版 buildResult 一致）
+		expect(result.details.answers["Which database?"]).toBe("Postgres");
+	});
+
+	it("R-8: multi-question mixed (single-select + multi-select + Other + comment)", async () => {
+		const tool = getTool();
+		const mixed = {
+			questions: [
+				{
+					question: "Which database?",
+					header: "DB",
+					options: [{ label: "Postgres" }, { label: "MySQL" }],
+				},
+				{
+					question: "Which tools?",
+					header: "Tools",
+					options: [{ label: "A" }, { label: "B" }, { label: "C" }],
+					multiSelect: true,
+				},
+				{
+					question: "Which region?",
+					header: "Region",
+					options: [{ label: "US" }, { label: "EU" }],
+					allowComment: true,
+				},
+			],
+		};
+		// Q1: single-select Postgres
+		// Q2: multi-select [C, A] (乱序 → 应重排为 A, C) + Other "Custom"
+		// Q3: 无选中 (parts.length === 0 → skip, 不出现在 answers 中)
+		const protoAnswers = JSON.stringify({
+			DB: "Postgres",
+			Tools: JSON.stringify(["C", "A"]),
+			"Tools__other": "Custom",
+			// Region 无选中 → protoAnswersToResult 的 `if (parts.length === 0) continue` 跳过
+		});
+		const result = await tool.execute(
+			"id",
+			mixed,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+
+		expect(result.details.cancelled).toBe(false);
+		// Q1: single-select
+		expect(result.details.answers["Which database?"]).toBe("Postgres");
+		// Q2: multi-select 重排 + Other
+		expect(result.details.answers["Which tools?"]).toBe("A, C, Custom");
+		// Q3: 无选中 → 跳过（不在 answers map 中）
+		expect(result.details.answers["Which region?"]).toBeUndefined();
+	});
+
+	it("R-9: multi-question with comment on one question", async () => {
+		const tool = getTool();
+		const multiQ = {
+			questions: [
+				{
+					question: "Which DB?",
+					header: "DB",
+					options: [{ label: "Postgres" }],
+				},
+				{
+					question: "Why?",
+					header: "Reason",
+					options: [{ label: "Performance" }],
+					allowComment: true,
+				},
+			],
+		};
+		const protoAnswers = JSON.stringify({
+			DB: "Postgres",
+			Reason: "Performance",
+			"Reason__comment": "benchmarked",
+		});
+		const result = await tool.execute(
+			"id",
+			multiQ,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+
+		// Q1: 无 comment
+		expect(result.details.answers["Which DB?"]).toBe("Postgres");
+		// Q2: 有 comment → 内联
+		expect(result.details.answers["Why?"]).toBe("Performance — benchmarked");
+	});
+});