@zhushanwen/pi-ask-user 0.0.1

package/src/types.ts

@@ -0,0 +1,128 @@
+// src/types.ts
+import { type Static, Type } from "@sinclair/typebox";
+
+// ── 常量 ─────────────────────────────────────────────
+export const OTHER_LABEL = "Other";
+export const HEADER_MAX_CHARS = 12;
+/** question 文本长度上限：保证 details.answers 的 key 有界、可预测（spec FR-2） */
+export const QUESTION_MAX_CHARS = 1000;
+export const SPLIT_PANE_MIN_WIDTH = 84;
+export const SPLIT_PANE_SEPARATOR = " │ ";
+export const SPLIT_PANE_LEFT_MIN = 32;
+export const SPLIT_PANE_RIGHT_MIN = 28;
+export const ANSWER_COMMENT_SEPARATOR = " — ";
+
+// ── Input schema（LLM 调用参数） ─────────────────────
+// description 用英文：这些字符串会进 LLM 的 tool schema，英文更利于模型理解。
+export const OptionSchema = Type.Object({
+	label: Type.String({
+		description:
+			"Short, mutually exclusive option label (also the answer value returned to the LLM — keep it concise, ≤ ~40 chars). To recommend an option, prefix its label with '(Recommended)' and list it first.",
+	}),
+	description: Type.Optional(
+		Type.String({
+			description:
+				"Short rationale shown under the label and in the split-pane preview. Helps the user decide — explain the tradeoff, don't restate the label.",
+		}),
+	),
+});
+
+export const QuestionSchema = Type.Object({
+	question: Type.String({
+		description:
+			"Full question text. Must be one self-contained decision; avoid multi-part questions. Plain text only (no newlines or control characters).",
+	}),
+	header: Type.Optional(
+		Type.String({
+			description:
+				"Tab label, <=12 chars, required when questions.length > 1. Omit for a single question.",
+		}),
+	),
+	context: Type.Optional(Type.String({ description: "Short context summary shown above the question. Pass what you learned from read/grep so the user can answer without re-explaining." })),
+	options: Type.Array(OptionSchema, {
+		minItems: 2,
+		maxItems: 4,
+		description: "2-4 mutually exclusive options. Each must be a defensible standalone answer; do NOT include an 'Other' option — it is added automatically.",
+	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({ description: "Default false. Set true only when more than one option can validly apply simultaneously; otherwise leave false for a single best answer." }),
+	),
+	allowComment: Type.Optional(
+		Type.Boolean({ description: "Default false. Set true to let the user append a short free-text comment after selecting (e.g. to note a constraint)." }),
+	),
+});
+
+export const InputSchema = Type.Object({
+	questions: Type.Array(QuestionSchema, {
+		minItems: 1,
+		maxItems: 4,
+		description: "1-4 questions, each a single decision. Batch only related decisions that the user should resolve together; otherwise ask the most important one alone.",
+	}),
+});
+
+// ── 派生类型 ─────────────────────────────────────────
+export type Option = Static<typeof OptionSchema>;
+export type Question = Static<typeof QuestionSchema>;
+export type Input = Static<typeof InputSchema>;
+
+// ── Result schema（details，renderResult 数据源） ─────
+export const ResultSchema = Type.Object({
+	questions: Type.Array(QuestionSchema),
+	answers: Type.Record(Type.String(), Type.String()),
+	cancelled: Type.Boolean(),
+});
+
+export type Result = Static<typeof ResultSchema>;
+
+/** execute 意外异常时返回的错误 details（区别于 Result.cancelled 的业务取消） */
+export interface ErrorDetails {
+	error: string;
+}
+
+/** execute 返回的 details 联合：正常/取消/校验失败走 Result，意外异常走 ErrorDetails */
+export type AskUserDetails = Result | ErrorDetails;
+
+// ── 跨模块共享的交互状态类型 ─────────────────────────
+// 放这里（而非 component.ts）是为了让 question-view.ts / submit-view.ts
+// 这两个纯渲染函数只依赖 types.ts，不反向依赖 component.ts（消除循环依赖）。
+
+/** TUI 颜色主题的最小接口（满足真实 Theme 和测试 stub） */
+export interface ThemeLike {
+	fg(token: string, text: string): string;
+	bg(token: string, text: string): string;
+	bold(text: string): string;
+}
+
+/** 单问题的交互模式 */
+export type QuestionMode = "options" | "freeform" | "comment";
+
+/** 单问题的交互状态（每问题一个实例） */
+export interface QuestionState {
+	/** 光标位置（高亮的选项，≠ 已选答案） */
+	cursorIndex: number;
+	/** 单选：显式选中的选项 index；null=未选 */
+	selectedIndex: number | null;
+	/** 多选：已 toggle 的选项 index 集合 */
+	selectedIndices: Set<number>;
+	/** 是否已确认（Submit 门的条件） */
+	confirmed: boolean;
+	/** Other 自由文本答案；null=未输入 */
+	freeTextValue: string | null;
+	/** 可选评论；null=未输入 */
+	commentValue: string | null;
+	/** 当前交互模式 */
+	mode: QuestionMode;
+}
+
+/** 创建初始 QuestionState */
+export function createQuestionState(): QuestionState {
+	return {
+		cursorIndex: 0,
+		selectedIndex: null,
+		selectedIndices: new Set<number>(),
+		confirmed: false,
+		freeTextValue: null,
+		commentValue: null,
+		mode: "options",
+	};
+}

package/src/validate.ts

@@ -0,0 +1,61 @@
+// src/validate.ts
+import { type Question,QUESTION_MAX_CHARS } from "./types";
+
+/** 控制字符（含 \n \r \t 等）：question 文本禁止包含，避免 answers key 含不可见字符（spec FR-2） */
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+
+/**
+ * 校验输入参数。通过返回 null，失败返回错误消息字符串。
+ * 校验项（spec FR-2）：
+ * - question 文本长度上限与无控制字符（保证 answers key 有界、可预测）
+ * - question 文本在数组内唯一
+ * - 同问题内 option label 唯一
+ * - 多问题（questions.length > 1）时每个 question 必须有非空 header
+ *
+ * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改）。
+ */
+export function validateInput(questions: Question[]): string | null {
+	const seenQuestions = new Set<string>();
+
+	for (const q of questions) {
+		const qt = q.question;
+
+		// 1a. question 文本长度上限（key 有界）
+		if (qt.length > QUESTION_MAX_CHARS) {
+			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, 20)}...". 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, 20)}...". Use plain single-line text; split multi-part questions into separate entries.`;
+		}
+
+		// 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);
+
+		// 2. option label 唯一且非空（空 label 会污染 details.answers 的值）
+		const seenLabels = new Set<string>();
+		for (const opt of q.options) {
+			if (opt.label.trim() === "") {
+				return `Option label must not be empty in question "${q.question}". Give every option a distinct, descriptive label.`;
+			}
+			if (seenLabels.has(opt.label)) {
+				return `Duplicate option label "${opt.label}" in question "${q.question}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
+			}
+			seenLabels.add(opt.label);
+		}
+	}
+
+	// 3. 多问题时 header 必填且非空
+	if (questions.length > 1) {
+		for (const q of questions) {
+			if (!q.header || q.header.trim() === "") {
+				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars.`;
+			}
+		}
+	}
+
+	return null;
+}