@zhushanwen/pi-ask-user 7.1.0 → 7.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.1.0",
+  "version": "7.1.2",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and an inline free-text editor.",
   "type": "module",
   "main": "index.ts",
@@ -29,8 +29,8 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.8.0",
-    "@zhushanwen/pi-extension-logger": "0.4.0"
+    "@xyz-agent/extension-protocol": "0.8.2",
+    "@zhushanwen/pi-extension-logger": "0.4.1"
   },
   "devDependencies": {
     "@earendil-works/pi-tui": "^0.84.4",

package/src/__tests__/component.test.ts

@@ -820,3 +820,35 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 		expect(lines.some((l: string) => l.includes("B"))).toBe(true);
 	});
 });
+
+// ── options 输入路由 no-op 落空语义（←/→ 与 Space 的守卫分支）──
+describe("AskUserComponent — options input no-op edges", () => {
+	it("C-NAV-1: single question ignores LEFT/RIGHT in options mode (no tab nav, no cancel overlay)", () => {
+		const { c, result } = make([singleQ]);
+		// 单问题无 tab：←/→ 应为 no-op（isSingle 短路），既不切 tab 也不进入确认取消覆盖层
+		c.handleInput(LEFT);
+		c.handleInput(RIGHT);
+		expect(result.val).toBeUndefined();
+		// 未进入 Esc 确认取消覆盖层（覆盖层特征文案不出现）
+		expect(c.render(60).some((l) => l.includes("Cancel all"))).toBe(false);
+		// 光标仍在第一项，表单完好
+		const lines = c.render(60);
+		expect(lines.some((l) => l.includes(">") && l.includes("Postgres"))).toBe(true);
+	});
+
+	it("C-NAV-2: multi-select Space on Other row is a no-op (does not toggle, does not enter editor)", () => {
+		const { c, result } = make([singleQMulti]);
+		// 下移到 Other 行（Auth, Search, Other → 光标 index 2）
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		// Other 行上 Space：multiSelect && !onOther 为 false → 落空
+		c.handleInput(" ");
+		// 未确认、未提交
+		expect(result.val).toBeUndefined();
+		const lines = c.render(60);
+		// Other 行未被 toggle（无任何 [✓] 勾选框出现）
+		expect(lines.some((l) => l.includes("[✓]"))).toBe(false);
+		// 仍在 options 模式（未进 freeform 编辑器——反色光标不出现）
+		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
+	});
+});

package/src/component.ts

@@ -214,6 +214,7 @@ export class AskUserComponent implements Component {
 	/**
 	 * options 模式的输入处理（从 handleInput 拆出）。
 	 * 含：Esc 回退/确认取消、←/→ 切 tab、↑/↓ 移光标、Enter 确认、Space toggle。
+	 * 主函数只留编排：Esc → tab 导航 → 光标导航 → 确认键，各阶段命中即终止。
 	 */
 	private handleOptionsInput(data: string, state: QuestionState, q: Question): void {
 		// Esc → 回退到上一个问题；在首个问题时进入确认取消覆盖层
@@ -221,59 +222,87 @@ export class AskUserComponent implements Component {
 			this.escBackOrConfirm();
 			return;
 		}
+		if (this.handleTabNavKeys(data)) return;
+		if (this.handleCursorNavKeys(data, state, q)) return;
+		this.handleOptionConfirmKeys(data, state, q);
+	}
 
-		// ← / → 切换问题 tab（多问题，options 模式）
+	/** ← / → 切换问题 tab（多问题，options 模式）。返回 true 表示已消费该按键。 */
+	private handleTabNavKeys(data: string): boolean {
 		if (!this.isSingle && matchesKey(data, "right")) {
 			this.gotoTab(Math.min(this.activeTab + 1, this.questions.length));
-			return;
+			return true;
 		}
 		if (!this.isSingle && matchesKey(data, "left")) {
 			this.gotoTab(Math.max(this.activeTab - 1, 0));
-			return;
+			return true;
 		}
+		return false;
+	}
 
+	/** ↑/↓ 移动选项光标（↓ 受 Other 行下界约束）。返回 true 表示已消费该按键。 */
+	private handleCursorNavKeys(data: string, state: QuestionState, q: Question): boolean {
 		if (matchesKey(data, "up")) {
 			state.cursorIndex = Math.max(0, state.cursorIndex - 1);
 			this.rerender();
-			return;
+			return true;
 		}
 		if (matchesKey(data, "down")) {
 			const max = allOptions(q).length - 1;
 			state.cursorIndex = Math.min(max, state.cursorIndex + 1);
 			this.rerender();
-			return;
+			return true;
 		}
+		return false;
+	}
 
+	/** Other 行 Enter 进编辑器 / 多选 Space toggle + Enter 确认 / 单选 Enter 确认。 */
+	private handleOptionConfirmKeys(data: string, state: QuestionState, q: Question): void {
 		const opts = allOptions(q);
 		const onOther = state.cursorIndex === opts.length - 1;
 
 		// Other row → Enter opens freeform editor
 		if (onOther && matchesKey(data, "enter")) {
-			state.savedOptionsCursorIndex = state.cursorIndex;
-			state.mode = "freeform";
-			state.draftText = state.freeTextValue ?? state.freeDraft ?? "";
-			state.cursorIndex = state.draftText.length;
-			this.rerender();
+			this.openOtherEditor(state);
 			return;
 		}
 
 		if (q.multiSelect && !onOther) {
-			if (matchesKey(data, "space")) {
-				this.toggleIndex(state, state.cursorIndex);
-				return;
-			}
-			if (matchesKey(data, "enter")) {
-				state.selectedIndices.add(state.cursorIndex);
-				this.afterConfirm(state);
-				return;
-			}
+			this.handleMultiSelectConfirmKeys(data, state);
 		} else if (!q.multiSelect && !onOther) {
-			if (matchesKey(data, "enter")) {
-				state.selectedIndex = state.cursorIndex;
-				state.freeTextValue = null;
-				this.afterConfirm(state);
-				return;
-			}
+			this.handleSingleSelectConfirmKeys(data, state);
+		}
+	}
+
+	/** Other 行 Enter：进 freeform 编辑器，预填已提交文本或上一次草稿。 */
+	private openOtherEditor(state: QuestionState): void {
+		state.savedOptionsCursorIndex = state.cursorIndex;
+		state.mode = "freeform";
+		state.draftText = state.freeTextValue ?? state.freeDraft ?? "";
+		state.cursorIndex = state.draftText.length;
+		this.rerender();
+	}
+
+	/** 多选（非 Other 行）：Space toggle；Enter 选中光标项并确认前进。 */
+	private handleMultiSelectConfirmKeys(data: string, state: QuestionState): void {
+		if (matchesKey(data, "space")) {
+			this.toggleIndex(state, state.cursorIndex);
+			return;
+		}
+		if (matchesKey(data, "enter")) {
+			state.selectedIndices.add(state.cursorIndex);
+			this.afterConfirm(state);
+			return;
+		}
+	}
+
+	/** 单选（非 Other 行）：Enter 选中光标项（清 Other 文本）并确认前进。 */
+	private handleSingleSelectConfirmKeys(data: string, state: QuestionState): void {
+		if (matchesKey(data, "enter")) {
+			state.selectedIndex = state.cursorIndex;
+			state.freeTextValue = null;
+			this.afterConfirm(state);
+			return;
 		}
 	}
 

package/src/question-view.ts

@@ -124,6 +124,7 @@ const EDITOR_HINT = " ←/→ Home/End move · Backspace deletes · Enter submit
 /**
  * 构建选项列表行（不含分屏预览）。hideDescriptions 用于分屏模式左列。
  *  freeform 模式下，Other 行**原地**变 [ ] <input> 反色光标（多选）/ <input> 反色光标（单选）。
+ * 主函数只留逐行编排：Other / 多选 / 单选三类行各自提取为独立 append helper。
  */
 function buildOptionLines(
 	ctx: RenderContext,
@@ -141,68 +142,108 @@ function buildOptionLines(
 		// 编辑器模式下用 savedOptionsCursorIndex 判断选项高亮，cursorIndex 此时是文本光标
 		const activeOptionCursor = state.mode === "freeform" ? state.savedOptionsCursorIndex : state.cursorIndex;
 		const isSelected = i === activeOptionCursor;
-		const isOther = opt.isOther === true;
 		const prefix = isSelected ? t.fg("accent", ">") : " ";
 
-		if (isOther) {
-			// 标记位宽度必须与普通选项一致，否则编号列错位：
-			//   单选 check = 1 列，多选 box = 3 列。
-			//   此前单选 freeform 占位用 "  "(2列)、多选非 freeform 用 check(1列)，
-			//   两种情况下 Other 编号都与普通选项错位。
-			if (state.mode === "freeform") {
-				const marker = q.multiSelect ? t.fg("dim", "[ ]") : " ";
-				const num = i + 1;
-				const lead = `${prefix} ${marker} `;
-				const avail = Math.max(1, width - visibleWidth(lead));
-				// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
-				const cursorText = renderCursorText(state.draftText, state.cursorIndex);
-				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
-				addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
-			} else {
-				const hasFreeText = state.freeTextValue !== null;
-				const marker = q.multiSelect
-					? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
-					: (hasFreeText ? t.fg("success", "✓") : " ");
-				const labelColor = isSelected ? "accent" : "text";
-				const num = i + 1;
-				add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-				if (hasFreeText) {
-					// 预览缩进对齐到 label 起始列：prefix + sp + marker + sp + "N." + sp。
-					// 随 num 位数与单/多选 marker 宽度动态变化，硬编码会错位。
-					const numStr = `${num}.`;
-					const lead = " ".repeat(
-						visibleWidth(prefix) + 1 + visibleWidth(marker) + 1 + numStr.length + 1,
-					);
-					const avail = Math.max(1, width - visibleWidth(lead));
-					const styled = t.fg("dim", `"${state.freeTextValue ?? ""}"`);
-					addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
-				}
-			}
+		if (opt.isOther === true) {
+			appendOtherRow(ctx, opt, i, isSelected, prefix, add);
 		} else if (q.multiSelect) {
-			const checked = state.selectedIndices.has(i);
-			const box = checked ? t.fg("accent", "[✓]") : t.fg("dim", "[ ]");
-			const labelColor = isSelected ? "accent" : "text";
-			const num = i + 1;
-			add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
-				for (const line of wrapped) add(`          ${line}`);
-			}
+			appendMultiSelectRow(ctx, opt, i, isSelected, prefix, hideDescriptions, add);
 		} else {
-			const isConfirmed = state.selectedIndex === i;
-			const check = isConfirmed ? t.fg("success", "✓") : " ";
-			const labelColor = isSelected ? "accent" : "text";
-			const num = i + 1;
-			add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
-			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
-				for (const line of wrapped) add(`        ${line}`);
-			}
+			appendSingleSelectRow(ctx, opt, i, isSelected, prefix, hideDescriptions, add);
 		}
 	}
 	return lines;
 }
 
+/** Other 行：freeform 原地编辑器（反色光标）/ 非 freeform 的 ✓ 标记 + 已保存文本预览。 */
+function appendOtherRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	add: (s: string) => void,
+): void {
+	const { question: q, state, theme: t, width } = ctx;
+	const num = index + 1;
+
+	if (state.mode === "freeform") {
+		// 标记位宽度必须与普通选项一致，否则编号列错位：
+		//   单选 check = 1 列，多选 box = 3 列。
+		//   此前单选 freeform 占位用 "  "(2列)、多选非 freeform 用 check(1列)，
+		//   两种情况下 Other 编号都与普通选项错位。
+		const marker = q.multiSelect ? t.fg("dim", "[ ]") : " ";
+		const lead = `${prefix} ${marker} `;
+		const avail = Math.max(1, width - visibleWidth(lead));
+		// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
+		const cursorText = renderCursorText(state.draftText, state.cursorIndex);
+		const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
+		addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+	} else {
+		const hasFreeText = state.freeTextValue !== null;
+		const marker = q.multiSelect
+			? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
+			: (hasFreeText ? t.fg("success", "✓") : " ");
+		const labelColor = isSelected ? "accent" : "text";
+		add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+		if (hasFreeText) {
+			// 预览缩进对齐到 label 起始列：prefix + sp + marker + sp + "N." + sp。
+			// 随 num 位数与单/多选 marker 宽度动态变化，硬编码会错位。
+			const numStr = `${num}.`;
+			const lead = " ".repeat(
+				visibleWidth(prefix) + 1 + visibleWidth(marker) + 1 + numStr.length + 1,
+			);
+			const avail = Math.max(1, width - visibleWidth(lead));
+			const styled = t.fg("dim", `"${state.freeTextValue ?? ""}"`);
+			addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
+		}
+	}
+}
+
+/** 多选普通选项行：勾选框 + 编号 label + 缩进描述（hideDescriptions 时省略描述）。 */
+function appendMultiSelectRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	hideDescriptions: boolean,
+	add: (s: string) => void,
+): void {
+	const { state, theme: t, width } = ctx;
+	const checked = state.selectedIndices.has(index);
+	const box = checked ? t.fg("accent", "[✓]") : t.fg("dim", "[ ]");
+	const labelColor = isSelected ? "accent" : "text";
+	const num = index + 1;
+	add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+	if (opt.description && !hideDescriptions) {
+		const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
+		for (const line of wrapped) add(`          ${line}`);
+	}
+}
+
+/** 单选普通选项行：✓ 确认标记 + 编号 label + 缩进描述（hideDescriptions 时省略描述）。 */
+function appendSingleSelectRow(
+	ctx: RenderContext,
+	opt: DisplayOption,
+	index: number,
+	isSelected: boolean,
+	prefix: string,
+	hideDescriptions: boolean,
+	add: (s: string) => void,
+): void {
+	const { state, theme: t, width } = ctx;
+	const isConfirmed = state.selectedIndex === index;
+	const check = isConfirmed ? t.fg("success", "✓") : " ";
+	const labelColor = isSelected ? "accent" : "text";
+	const num = index + 1;
+	add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
+	if (opt.description && !hideDescriptions) {
+		const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
+		for (const line of wrapped) add(`        ${line}`);
+	}
+}
+
 /** 构建分屏右侧 Markdown 详情预览。 */
 function buildPreviewLines(
 	ctx: RenderContext,

package/src/validate.ts

@@ -22,48 +22,74 @@ const ERROR_PREVIEW_CHARS = 20;
  * - 多问题（questions.length > 1）时每个 question 必须有非空 header
  *
  * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改），对结构误用附 Correct 正例。
+ *
+ * 主函数只留编排：逐 question 依序跑「文本 → 唯一性 → option labels」，再跑
+ * 多问题 header 校验与 header 长度校验。各阶段提取为独立 helper（?? 链按序短路求值，
+ * 与原 early-return 顺序一致）。校验顺序即错误优先级，不可调换。
  */
 export function validateInput(questions: InputQuestion[]): string | null {
 	const seenQuestions = new Set<string>();
 
 	for (const q of questions) {
 		const qt = q.question;
+		const perQuestionError =
+			checkQuestionText(qt) ??
+			checkDuplicateQuestion(qt, seenQuestions) ??
+			checkOptionLabels(qt, q.options);
+		if (perQuestionError) return perQuestionError;
+	}
 
-		// 1a. question 文本长度上限（key 有界）
-		if (qt.length > QUESTION_MAX_CHARS) {
-			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
-		}
-		// 1b. question 文本无控制字符（key 可预测，不影响下游渲染/解析）
-		if (CONTROL_CHAR_RE.test(qt)) {
-			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
-		}
+	return checkMultiQuestionHeaders(questions) ?? checkHeaderLengths(questions);
+}
 
-		// 1c. question 文本唯一
-		if (seenQuestions.has(qt)) {
-			return `Duplicate question: "${qt}". Each question text must be unique; merge duplicates or rephrase one to differ.`;
-		}
-		seenQuestions.add(qt);
+/** 1a. question 文本长度上限（key 有界）；1b. 无控制字符（key 可预测，不影响下游渲染/解析）。 */
+function checkQuestionText(qt: string): string | null {
+	if (qt.length > QUESTION_MAX_CHARS) {
+		return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
+	}
+	if (CONTROL_CHAR_RE.test(qt)) {
+		return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
+	}
+	return null;
+}
 
-		// 2. option 元素必须是 {label, description} 对象，不能是 string。
-		//    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
-		//    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
-		const seenLabels = new Set<string>();
-		for (const opt of q.options) {
-			if (typeof opt === "string") {
-				return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
-			}
-			// opt 已收窄为 Option
-			if (opt.label.trim() === "") {
-				return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
-			}
-			if (seenLabels.has(opt.label)) {
-				return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
-			}
-			seenLabels.add(opt.label);
+/** 1c. question 文本唯一。未重复时登记到 seenQuestions（调用方依赖此副作用）。 */
+function checkDuplicateQuestion(qt: string, seenQuestions: Set<string>): string | null {
+	if (seenQuestions.has(qt)) {
+		return `Duplicate question: "${qt}". Each question text must be unique; merge duplicates or rephrase one to differ.`;
+	}
+	seenQuestions.add(qt);
+	return null;
+}
+
+/**
+ * 2. option 元素必须是 {label, description} 对象，不能是 string。
+ *    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
+ *    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
+ */
+function checkOptionLabels(qt: string, options: InputQuestion["options"]): string | null {
+	const seenLabels = new Set<string>();
+	for (const opt of options) {
+		if (typeof opt === "string") {
+			return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
 		}
+		// opt 已收窄为 Option
+		if (opt.label.trim() === "") {
+			return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
+		}
+		if (seenLabels.has(opt.label)) {
+			return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
+		}
+		seenLabels.add(opt.label);
 	}
+	return null;
+}
 
-	// 3. 多问题时 header 必填且非空
+/**
+ * 3. 多问题时 header 必填且非空；S3: header 唯一——重复 header 会导致 askUserKey 碰撞，
+ * 后一个 question 的 __other 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
+ */
+function checkMultiQuestionHeaders(questions: InputQuestion[]): string | null {
 	if (questions.length > 1) {
 		for (const q of questions) {
 			if (!q.header || q.header.trim() === "") {
@@ -71,8 +97,6 @@ export function validateInput(questions: InputQuestion[]): string | null {
 			}
 		}
 
-		// S3: 多问题时 header 唯一——重复 header 会导致 askUserKey 碰撞，
-		// 后一个 question 的 __other 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
 		const seenHeaders = new Set<string>();
 		for (const q of questions) {
 			const h = q.header!.trim();
@@ -82,14 +106,18 @@ export function validateInput(questions: InputQuestion[]): string | null {
 			seenHeaders.add(h);
 		}
 	}
+	return null;
+}
 
-	// 4. header 长度上限（若提供）。单/多问题均校验：超出会在 tab 栏被静默截断，
-	//    这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
+/**
+ * 4. header 长度上限（若提供）。单/多问题均校验：超出会在 tab 栏被静默截断，
+ * 这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
+ */
+function checkHeaderLengths(questions: InputQuestion[]): string | null {
 	for (const q of questions) {
 		if (q.header !== undefined && q.header.length > HEADER_MAX_CHARS) {
 			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, ERROR_PREVIEW_CHARS)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
 		}
 	}
-
 	return null;
 }