@ryan_nookpi/pi-extension-ask-user-question 0.2.2 → 0.3.1

package/README.md

@@ -88,3 +88,21 @@ pi install npm:@ryan_nookpi/pi-extension-ask-user-question
 ## 반환 형태
 
 응답은 각 질문의 `id` 기준으로 정리되어 반환됩니다. 취소 시에는 `cancelled: true`가 내려오고, 완료 시에는 질문별 답변 목록이 포함됩니다.
+
+## 허용되는 느슨한 입력 형태
+
+위 스키마가 권장 형식이지만, 다음과 같은 변형 입력도 자동으로 정규화해서 처리합니다.
+
+- `questions`를 JSON 문자열로 직렬화해 전달: `{ "questions": "[ ... ]" }`
+- 질문 프롬프트를 `prompt` 대신 `question` 필드로 전달
+- `options`를 `{ value, label }` 객체가 아닌 문자열 배열로 전달 (동일 값으로 승격)
+- `options`를 JSON 문자열로 직렬화해 전달
+- `id` 생략 시 순서대로 `q1`, `q2`, ...로 자동 부여
+
+예:
+
+```json
+{
+  "questions": "[{\"type\": \"radio\", \"question\": \"extension 이름\", \"options\": [\"claude-code-use\", \"pi-claude-code-use\"], \"allowOther\": true}]"
+}
+```

package/coerce.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+
+import { coerceAskUserQuestionParams } from "./coerce.ts";
+
+describe("coerceAskUserQuestionParams", () => {
+	it("구조화된 파라미터를 그대로 보존한다", () => {
+		const input = {
+			title: "Title",
+			description: "Desc",
+			questions: [
+				{
+					id: "env",
+					type: "radio",
+					prompt: "어느 환경?",
+					options: [
+						{ value: "staging", label: "스테이징" },
+						{ value: "prod", label: "프로덕션", description: "실서비스" },
+					],
+					allowOther: false,
+					required: true,
+					default: "staging",
+				},
+			],
+		};
+
+		const result = coerceAskUserQuestionParams(input);
+		expect(result).toEqual(input);
+	});
+
+	it("JSON 문자열로 전달된 questions를 파싱한다", () => {
+		const payload = {
+			questions: JSON.stringify([
+				{
+					type: "radio",
+					question: "파일 배치 구조",
+					options: ["directory", "single file", "single file + flat"],
+					allowOther: true,
+				},
+				{
+					type: "checkbox",
+					question: "포함 여부",
+					options: ["LICENSE", "author attribution"],
+				},
+				{
+					type: "text",
+					question: "추가 메모",
+					placeholder: "선택 사항",
+					required: false,
+				},
+			]),
+		};
+
+		const result = coerceAskUserQuestionParams(payload);
+
+		expect(result.questions).toHaveLength(3);
+		expect(result.questions[0]).toEqual({
+			id: "q1",
+			type: "radio",
+			prompt: "파일 배치 구조",
+			options: [
+				{ value: "directory", label: "directory" },
+				{ value: "single file", label: "single file" },
+				{ value: "single file + flat", label: "single file + flat" },
+			],
+			allowOther: true,
+		});
+		expect(result.questions[1].id).toBe("q2");
+		expect(result.questions[1].type).toBe("checkbox");
+		expect(result.questions[1].options).toEqual([
+			{ value: "LICENSE", label: "LICENSE" },
+			{ value: "author attribution", label: "author attribution" },
+		]);
+		expect(result.questions[2]).toEqual({
+			id: "q3",
+			type: "text",
+			prompt: "추가 메모",
+			placeholder: "선택 사항",
+			required: false,
+		});
+	});
+
+	it("question 별칭과 options JSON 문자열을 지원한다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				{
+					type: "radio",
+					question: "extension 이름",
+					options: JSON.stringify(["claude-code-use", "pi-claude-code-use"]),
+				},
+			],
+		});
+
+		expect(result.questions[0].prompt).toBe("extension 이름");
+		expect(result.questions[0].options).toEqual([
+			{ value: "claude-code-use", label: "claude-code-use" },
+			{ value: "pi-claude-code-use", label: "pi-claude-code-use" },
+		]);
+	});
+
+	it("잘못된 입력을 조용히 걸러낸다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				null,
+				{ type: "radio" }, // prompt 없음 -> 제외
+				{ type: "unknown", prompt: "?" }, // 잘못된 type -> 제외
+				{ type: "text", prompt: "OK" },
+				"not-an-object",
+			],
+		});
+
+		expect(result.questions).toHaveLength(1);
+		expect(result.questions[0]).toMatchObject({ id: "q4", type: "text", prompt: "OK" });
+	});
+
+	it("questions 자체가 누락되거나 비-객체 입력이면 빈 배열을 돌려준다", () => {
+		expect(coerceAskUserQuestionParams(null).questions).toEqual([]);
+		expect(coerceAskUserQuestionParams(undefined).questions).toEqual([]);
+		expect(coerceAskUserQuestionParams({ questions: "not-json" }).questions).toEqual([]);
+		expect(coerceAskUserQuestionParams({ questions: '{"not":"array"}' }).questions).toEqual([]);
+	});
+
+	it("checkbox default가 배열이면 문자열만 남겨 보존한다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				{
+					type: "checkbox",
+					prompt: "포함할 항목",
+					options: ["a", "b", "c"],
+					default: ["a", 42, "b", null],
+				},
+			],
+		});
+		expect(result.questions[0].default).toEqual(["a", "b"]);
+	});
+
+	it("default 배열에서 유효 문자열이 없으면 기본값을 비워 둔다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				{
+					type: "checkbox",
+					prompt: "포함할 항목",
+					options: ["a", "b"],
+					default: [1, 2, null],
+				},
+			],
+		});
+		expect(result.questions[0].default).toBeUndefined();
+	});
+
+	it("질문 수준의 label, empty/non-string 옵션, JSON 되는 빈 문자열 등 세부 변형을 사장 없이 무시한다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				{
+					id: "labelled",
+					type: "radio",
+					prompt: "완전한 질문",
+					label: "Short label",
+					options: [
+						"   ", // empty string option -> dropped
+						42, // non-string, non-object option -> dropped
+						{ label: "Label only" }, // label -> promoted to value
+						{ value: "raw-value" }, // value -> promoted to label
+						{ description: "no label/value" }, // dropped
+						{ value: "v", label: "L", description: "with description" },
+					],
+				},
+			],
+		});
+
+		expect(result.questions[0].label).toBe("Short label");
+		expect(result.questions[0].options).toEqual([
+			{ value: "Label only", label: "Label only" },
+			{ value: "raw-value", label: "raw-value" },
+			{ value: "v", label: "L", description: "with description" },
+		]);
+	});
+
+	it("빈 문자열 questions 필드는 빈 배열로 간주한다", () => {
+		expect(coerceAskUserQuestionParams({ questions: "   " }).questions).toEqual([]);
+	});
+
+	it("공백만 있는 prompt/label 문자열은 없는 것으로 간주한다", () => {
+		const result = coerceAskUserQuestionParams({
+			questions: [
+				{ type: "radio", prompt: "   " }, // whitespace prompt -> dropped
+				{ type: "text", prompt: "valid", label: "   " }, // whitespace label -> ignored
+			],
+		});
+		expect(result.questions).toHaveLength(1);
+		expect(result.questions[0]).toMatchObject({ type: "text", prompt: "valid" });
+		expect(result.questions[0].label).toBeUndefined();
+	});
+});

package/coerce.ts

@@ -0,0 +1,121 @@
+import type { AskUserQuestionParamsInput, Question, QuestionOption } from "./types.ts";
+
+/**
+ * 느슨한 입력을 정규화된 파라미터로 변환한다.
+ *
+ * 허용하는 변형:
+ * - `questions`가 JSON 문자열이면 파싱한다.
+ * - 질문의 `question` 필드를 `prompt` 별칭으로 받는다.
+ * - `options`가 문자열 배열이면 `{ value, label }` 형태로 승격한다.
+ * - `options`가 JSON 문자열이면 파싱한다.
+ * - `id`가 없으면 `q1`, `q2` 형태로 자동 생성한다.
+ */
+export function coerceAskUserQuestionParams(raw: unknown): AskUserQuestionParamsInput {
+	if (raw == null || typeof raw !== "object") {
+		return { questions: [] };
+	}
+
+	const record = raw as Record<string, unknown>;
+	const title = typeof record.title === "string" ? record.title : undefined;
+	const description = typeof record.description === "string" ? record.description : undefined;
+	const questions = coerceQuestionList(record.questions);
+
+	return { title, description, questions };
+}
+
+function coerceQuestionList(value: unknown): Question[] {
+	const list = parseMaybeJsonArray(value);
+	if (!list) return [];
+
+	return list
+		.map((item, index) => coerceQuestion(item, index))
+		.filter((question): question is Question => question != null);
+}
+
+function coerceQuestion(value: unknown, index: number): Question | null {
+	if (value == null || typeof value !== "object") return null;
+	const record = value as Record<string, unknown>;
+
+	const type = coerceType(record.type);
+	if (!type) return null;
+
+	const prompt = coerceString(record.prompt) ?? coerceString(record.question);
+	if (!prompt) return null;
+
+	const id = coerceString(record.id) ?? `q${index + 1}`;
+	const question: Question = { id, type, prompt };
+
+	const label = coerceString(record.label);
+	if (label) question.label = label;
+
+	const options = coerceOptions(record.options);
+	if (options.length > 0) question.options = options;
+
+	if (typeof record.allowOther === "boolean") question.allowOther = record.allowOther;
+	if (typeof record.required === "boolean") question.required = record.required;
+
+	const placeholder = coerceString(record.placeholder);
+	if (placeholder) question.placeholder = placeholder;
+
+	const defaultValue = coerceDefault(record.default);
+	if (defaultValue !== undefined) question.default = defaultValue;
+
+	return question;
+}
+
+function coerceOptions(value: unknown): QuestionOption[] {
+	const list = parseMaybeJsonArray(value);
+	if (!list) return [];
+
+	return list.map((item) => coerceOption(item)).filter((option): option is QuestionOption => option != null);
+}
+
+function coerceOption(value: unknown): QuestionOption | null {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (!trimmed) return null;
+		return { value: trimmed, label: trimmed };
+	}
+	if (value == null || typeof value !== "object") return null;
+	const record = value as Record<string, unknown>;
+	const rawValue = coerceString(record.value) ?? coerceString(record.label);
+	const rawLabel = coerceString(record.label) ?? coerceString(record.value);
+	if (!rawValue || !rawLabel) return null;
+	const option: QuestionOption = { value: rawValue, label: rawLabel };
+	const description = coerceString(record.description);
+	if (description) option.description = description;
+	return option;
+}
+
+function coerceType(value: unknown): "radio" | "checkbox" | "text" | null {
+	if (value === "radio" || value === "checkbox" || value === "text") return value;
+	return null;
+}
+
+function coerceString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function coerceDefault(value: unknown): string | string[] | undefined {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		const strings = value.filter((item): item is string => typeof item === "string");
+		return strings.length > 0 ? strings : undefined;
+	}
+	return undefined;
+}
+
+function parseMaybeJsonArray(value: unknown): unknown[] | null {
+	if (Array.isArray(value)) return value;
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	try {
+		const parsed = JSON.parse(trimmed);
+		return Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}

package/index.test.ts

@@ -42,11 +42,65 @@ describe("ask-user-question extension", () => {
 			hasUI: true,
 			ui: { custom: vi.fn() },
 		} as unknown as ExtensionContext);
+		const invalidQuestions = await tool.execute(
+			"call-2b",
+			{ title: "Title", questions: "not-json" },
+			undefined,
+			undefined,
+			{ hasUI: true, ui: { custom: vi.fn() } } as unknown as ExtensionContext,
+		);
 
 		expect(noUi).toMatchObject({
 			content: [{ type: "text", text: "오류: UI를 사용할 수 없습니다. 현재 비대화형 모드에서 실행 중입니다." }],
 		});
 		expect(noQuestions).toMatchObject({ content: [{ type: "text", text: "오류: 질문이 제공되지 않았습니다." }] });
+		expect(invalidQuestions).toMatchObject({ content: [{ type: "text", text: "오류: 질문이 제공되지 않았습니다." }] });
+	});
+
+	it("JSON 문자열로 직렬화된 questions도 폼 실행 경로로 진입한다", async () => {
+		const apiMock = createExtensionApiMock();
+		askUserQuestionExtension(apiMock.api);
+		const tool = apiMock.getTool("ask_user_question");
+		if (!tool.execute) throw new Error("execute is missing");
+
+		const customMock = vi.fn(async () => ({
+			title: undefined,
+			questions: normalizeQuestions([
+				{
+					id: "q1",
+					type: "radio",
+					prompt: "extension 이름",
+					options: [
+						{ value: "claude-code-use", label: "claude-code-use" },
+						{ value: "pi-claude-code-use", label: "pi-claude-code-use" },
+					],
+				},
+			]),
+			answers: [{ id: "q1", type: "radio" as const, value: "claude-code-use", wasCustom: false }],
+			cancelled: false,
+		}));
+
+		const serializedResult = await tool.execute(
+			"call-json",
+			{
+				questions: JSON.stringify([
+					{
+						type: "radio",
+						question: "extension 이름",
+						options: ["claude-code-use", "pi-claude-code-use"],
+						allowOther: true,
+					},
+				]),
+			},
+			undefined,
+			undefined,
+			{ hasUI: true, ui: { custom: customMock } } as unknown as ExtensionContext,
+		);
+
+		expect(customMock).toHaveBeenCalledTimes(1);
+		expect(serializedResult).toMatchObject({
+			content: [{ type: "text", text: "Q1: claude-code-use" }],
+		});
 	});
 
 	it("returns cancelled and successful execution results", async () => {

package/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
+import { coerceAskUserQuestionParams } from "./coerce.ts";
 import { runAskUserQuestionForm } from "./form-ui.ts";
 import {
 	buildRenderCallText,
@@ -44,7 +45,14 @@ function buildSuccessResponse(result: FormResult) {
 }
 
 export type { AskUserQuestionParamsInput, FormResult, Question };
-export { AskUserQuestionParams, buildRenderCallText, buildRenderResultText, errorResult, normalizeQuestions };
+export {
+	AskUserQuestionParams,
+	buildRenderCallText,
+	buildRenderResultText,
+	coerceAskUserQuestionParams,
+	errorResult,
+	normalizeQuestions,
+};
 
 export default function askUserQuestion(pi: ExtensionAPI) {
 	pi.registerTool({
@@ -59,12 +67,12 @@ export default function askUserQuestion(pi: ExtensionAPI) {
 				return errorResult("오류: UI를 사용할 수 없습니다. 현재 비대화형 모드에서 실행 중입니다.");
 			}
 
-			const params = rawParams as AskUserQuestionParamsInput;
+			const params = coerceAskUserQuestionParams(rawParams);
 			if (!params.questions.length) {
 				return errorResult("오류: 질문이 제공되지 않았습니다.");
 			}
 
-			const questions = normalizeQuestions(params.questions as Question[]);
+			const questions = normalizeQuestions(params.questions);
 			const result = await runAskUserQuestionForm(
 				ctx,
 				{ title: params.title, description: params.description },
@@ -73,10 +81,8 @@ export default function askUserQuestion(pi: ExtensionAPI) {
 			return result.cancelled ? buildCancelledResponse(result) : buildSuccessResponse(result);
 		},
 		renderCall(args, theme) {
-			return renderCall(
-				{ questions: args.questions as Question[] | undefined, title: args.title as string | undefined },
-				theme,
-			);
+			const coerced = coerceAskUserQuestionParams(args);
+			return renderCall({ questions: coerced.questions, title: coerced.title }, theme);
 		},
 		renderResult(result, _options, theme) {
 			return renderResult(result as { content?: Array<{ type: string; text?: string }>; details?: FormResult }, theme);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-ask-user-question",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "AskUserQuestion tool extension for pi.",
   "license": "MIT",
   "repository": {

package/schema.test.ts

@@ -0,0 +1,20 @@
+import { Value } from "@sinclair/typebox/value";
+import { describe, expect, it } from "vitest";
+
+import { AskUserQuestionParams } from "./schema.ts";
+
+describe("ask-user-question/schema", () => {
+	it("질문 배열 JSON 문자열과 느슨한 질문 필드를 허용한다", () => {
+		const payload = {
+			questions: JSON.stringify([
+				{
+					question: "오늘 기분이 어떠세요?",
+					type: "radio",
+					options: ["좋음", "보통", "나쁨"],
+				},
+			]),
+		};
+
+		expect(Value.Check(AskUserQuestionParams, payload)).toBe(true);
+	});
+});

package/schema.ts

@@ -7,14 +7,25 @@ export const OptionSchema = Type.Object({
 	description: Type.Optional(Type.String({ description: "옵션 아래에 표시할 보조 설명" })),
 });
 
+export const LooseOptionSchema = Type.Union([
+	OptionSchema,
+	Type.String({ description: "문자열 선택지. value/label이 같은 값으로 처리됨" }),
+]);
+
 export const QuestionSchema = Type.Object({
-	id: Type.String({ description: "질문 고유 식별자" }),
+	id: Type.Optional(Type.String({ description: "질문 고유 식별자. 생략 시 q1, q2...로 자동 생성" })),
 	type: StringEnum(["radio", "checkbox", "text"] as const, {
 		description: "질문 유형: radio(단일 선택), checkbox(복수 선택), text(자유 입력)",
 	}),
-	prompt: Type.String({ description: "사용자에게 표시할 질문 문구" }),
+	prompt: Type.Optional(Type.String({ description: "사용자에게 표시할 질문 문구" })),
+	question: Type.Optional(Type.String({ description: "prompt 별칭" })),
 	label: Type.Optional(Type.String({ description: "탭 바에 표시할 짧은 라벨(기본값: Q1, Q2...)" })),
-	options: Type.Optional(Type.Array(OptionSchema, { description: "radio/checkbox용 선택지 목록" })),
+	options: Type.Optional(
+		Type.Union([
+			Type.Array(LooseOptionSchema, { description: "radio/checkbox용 선택지 목록" }),
+			Type.String({ description: "선택지 배열을 직렬화한 JSON 문자열" }),
+		]),
+	),
 	allowOther: Type.Optional(
 		Type.Boolean({ description: "'기타...' 직접 입력 옵션 추가 여부 (radio/checkbox 기본값: true)" }),
 	),
@@ -30,7 +41,10 @@ export const QuestionSchema = Type.Object({
 export const AskUserQuestionParams = Type.Object({
 	title: Type.Optional(Type.String({ description: "폼 상단에 표시할 제목" })),
 	description: Type.Optional(Type.String({ description: "폼 상단에 표시할 안내 문구" })),
-	questions: Type.Array(QuestionSchema, {
-		description: "질문 목록. radio는 단일 선택, checkbox는 복수 선택, text는 자유 입력",
-	}),
+	questions: Type.Union([
+		Type.Array(QuestionSchema, {
+			description: "질문 목록. radio는 단일 선택, checkbox는 복수 선택, text는 자유 입력",
+		}),
+		Type.String({ description: "질문 배열을 직렬화한 JSON 문자열" }),
+	]),
 });