@henryqw/pi-ask-question 0.1.10 → 0.2.0

package/README.md

@@ -30,4 +30,6 @@ pi install npm:@henryqw/pi-ask-question
 }
 ```
 
-Supply one to three options in preference order. UI marks the first `(Recommended)` and adds `Something else.` for a custom answer. Number keys select options. Empty questions, blank or duplicate labels, empty lists, more than three options, and non-interactive sessions return an error. Aborting the tool closes the pending question.
+Supply one to three options in preference order. UI marks the first `(Recommended)` and adds `Something else.`, which opens a text input for a custom answer. Empty questions, blank or duplicate labels, empty lists, more than three options, and non-interactive sessions return an error. Aborting the tool closes the pending question.
+
+Extensions can reuse the same validated interaction with the `askQuestion(params, ctx, signal)` package export; it returns the tool's answer details without registering another UI flow.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface AskQuestionOption {
+    label: string;
+    description?: string;
+}
+export interface AskQuestionRequest {
+    question: string;
+    options: AskQuestionOption[];
+}
+export interface AskQuestionResult {
+    question: string;
+    options: string[];
+    answer: string | null;
+    wasCustom?: boolean;
+    selectedIndex?: number;
+    error?: string;
+}
+type AskQuestionContext = Pick<ExtensionContext, "mode" | "ui">;
+/** Run the validated interactive question flow shared by consumers. */
+export declare function askQuestion(params: AskQuestionRequest, ctx: AskQuestionContext, signal?: AbortSignal): Promise<AskQuestionResult>;
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+const CUSTOM_OPTION_LABEL = "Something else.";
+const RECOMMENDED_SUFFIX = /\s*\(recommended\)\s*$/i;
+const withRecommended = (label) => `${label.replace(RECOMMENDED_SUFFIX, "")} (Recommended)`;
+/** Run the validated interactive question flow shared by consumers. */
+export async function askQuestion(params, ctx, signal) {
+    const question = params.question.trim();
+    const suppliedOptions = params.options.map((option) => ({
+        label: option.label.trim(),
+        ...(option.description === undefined ? {} : { description: option.description.trim() }),
+    }));
+    const options = suppliedOptions.map((option) => option.label);
+    if (ctx.mode !== "tui") {
+        const error = "UI not available (running in non-interactive mode)";
+        return { question, options, answer: null, error };
+    }
+    let validationError;
+    if (!question)
+        validationError = "Question must not be blank";
+    else if (suppliedOptions.length < 1 || suppliedOptions.length > 3)
+        validationError = "Provide one to three options";
+    else if (suppliedOptions.some((option) => !option.label))
+        validationError = "Option labels must not be blank";
+    else if (new Set(options.map((option) => option.toLowerCase())).size !== options.length)
+        validationError = "Option labels must be unique";
+    else if (options.some((option) => option.toLowerCase() === CUSTOM_OPTION_LABEL.toLowerCase()))
+        validationError = `Option label "${CUSTOM_OPTION_LABEL}" is reserved`;
+    if (validationError)
+        return { question, options, answer: null, error: validationError };
+    const choices = suppliedOptions.map((option, index) => {
+        const label = index === 0 ? withRecommended(option.label) : option.label;
+        return `${index + 1}. ${label}${option.description ? ` — ${option.description}` : ""}`;
+    });
+    choices.push(`${choices.length + 1}. ${CUSTOM_OPTION_LABEL}`);
+    const selected = await ctx.ui.select(question, choices, { signal });
+    const selectedIndex = selected === undefined ? -1 : choices.indexOf(selected);
+    const wasCustom = selectedIndex === suppliedOptions.length;
+    const answer = wasCustom
+        ? (await ctx.ui.input(CUSTOM_OPTION_LABEL, "Type your answer", { signal }))?.trim()
+        : suppliedOptions[selectedIndex]?.label;
+    if (!answer)
+        return { question, options, answer: null };
+    return {
+        question,
+        options,
+        answer,
+        wasCustom,
+        selectedIndex: wasCustom ? undefined : selectedIndex + 1,
+    };
+}

package/extensions/ask-question.ts

@@ -1,37 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	Editor,
-	type EditorTheme,
-	Key,
-	type KeyId,
-	matchesKey,
-	Text,
-	visibleWidth,
-	wrapTextWithAnsi,
-} from "@earendil-works/pi-tui";
+import { askQuestion } from "@henryqw/pi-ask-question";
 import { Type } from "typebox";
 
-interface QuestionOption {
-	label: string;
-	description?: string;
-}
-
-type DisplayOption = QuestionOption & { isOther?: boolean };
-
-const CUSTOM_OPTION_LABEL = "Something else.";
-// Models are told to omit "(Recommended)" from labels but don't always comply; normalize instead of duplicating.
-const RECOMMENDED_SUFFIX = /\s*\(recommended\)\s*$/i;
-const withRecommended = (label: string): string => `${label.replace(RECOMMENDED_SUFFIX, "")} (Recommended)`;
-
-interface QuestionDetails {
-	question: string;
-	options: string[];
-	answer: string | null;
-	wasCustom?: boolean;
-	selectedIndex?: number;
-	error?: string;
-}
-
 const QuestionOptionSchema = Type.Object({
 	label: Type.String({ description: "Display label for the option", minLength: 1 }),
 	description: Type.Optional(Type.String({ description: "Optional description shown below label", minLength: 1 })),
@@ -61,195 +31,20 @@ export default function askQuestionExtension(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const question = params.question.trim();
-			const suppliedOptions = params.options.map((option) => ({
-				label: option.label.trim(),
-				...(option.description === undefined ? {} : { description: option.description.trim() }),
-			}));
-			const options = suppliedOptions.map((option) => option.label);
-			if (ctx.mode !== "tui") {
-				const error = "UI not available (running in non-interactive mode)";
-				return {
-					content: [{ type: "text" as const, text: `Error: ${error}` }],
-					details: { question, options, answer: null, error } satisfies QuestionDetails,
-				};
-			}
-			let validationError: string | undefined;
-			if (!question) validationError = "Question must not be blank";
-			else if (suppliedOptions.some((option) => !option.label)) validationError = "Option labels must not be blank";
-			else if (new Set(options.map((option) => option.toLowerCase())).size !== options.length) validationError = "Option labels must be unique";
-			else if (options.some((option) => option.toLowerCase() === CUSTOM_OPTION_LABEL.toLowerCase())) validationError = `Option label "${CUSTOM_OPTION_LABEL}" is reserved`;
-			if (validationError) {
-				return {
-					content: [{ type: "text" as const, text: `Error: ${validationError}` }],
-					details: { question, options, answer: null, error: validationError } satisfies QuestionDetails,
-				};
-			}
-
-			const allOptions: DisplayOption[] = [...suppliedOptions, { label: CUSTOM_OPTION_LABEL, isOther: true }];
-			const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>(
-				(tui, theme, _kb, done) => {
-					let optionIndex = 0;
-					let editMode = false;
-					let cachedLines: string[] | undefined;
-					const editorTheme: EditorTheme = {
-						borderColor: (text) => theme.fg("accent", text),
-						selectList: {
-							selectedPrefix: (text) => theme.fg("accent", text),
-							selectedText: (text) => theme.fg("accent", text),
-							description: (text) => theme.fg("muted", text),
-							scrollInfo: (text) => theme.fg("dim", text),
-							noMatch: (text) => theme.fg("warning", text),
-						},
-					};
-					const editor = new Editor(tui, editorTheme);
-
-					function refresh(): void {
-						cachedLines = undefined;
-						tui.requestRender();
-					}
-
-					editor.onSubmit = (value) => {
-						const answer = value.trim();
-						if (answer) done({ answer, wasCustom: true });
-						else {
-							editMode = false;
-							editor.setText("");
-							refresh();
-						}
-					};
-
-					function selectOption(): void {
-						const selected = allOptions[optionIndex]!;
-						if (selected.isOther) editMode = true;
-						else done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 });
-					}
-
-					function handleInput(data: string): void {
-						if (editMode) {
-							if (matchesKey(data, Key.escape)) {
-								editMode = false;
-								editor.setText("");
-								refresh();
-								return;
-							}
-							editor.handleInput(data);
-							refresh();
-							return;
-						}
-
-						const numberIndex = allOptions.findIndex((_, index) => matchesKey(data, `${index + 1}` as KeyId));
-						if (numberIndex >= 0) {
-							optionIndex = numberIndex;
-							selectOption();
-						} else if (matchesKey(data, Key.up)) optionIndex = Math.max(0, optionIndex - 1);
-						else if (matchesKey(data, Key.down)) optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);
-						else if (matchesKey(data, Key.enter)) selectOption();
-						else if (matchesKey(data, Key.escape)) {
-							done(null);
-							return;
-						} else return;
-						refresh();
-					}
-
-					function render(width: number): string[] {
-						if (cachedLines) return cachedLines;
-						const lines: string[] = [];
-						const renderWidth = Math.max(1, width);
-						const addWrappedWithPrefix = (prefix: string, text: string): void => {
-							const prefixWidth = visibleWidth(prefix);
-							if (prefixWidth >= renderWidth) {
-								lines.push(...wrapTextWithAnsi(prefix + text, renderWidth));
-								return;
-							}
-							const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
-							const continuationPrefix = " ".repeat(prefixWidth);
-							for (let index = 0; index < wrapped.length; index++) {
-								lines.push(`${index === 0 ? prefix : continuationPrefix}${wrapped[index]}`);
-							}
-						};
-
-						lines.push(theme.fg("accent", "─".repeat(renderWidth)));
-						addWrappedWithPrefix(" ", theme.fg("text", question));
-						lines.push("");
-						for (let index = 0; index < allOptions.length; index++) {
-							const option = allOptions[index]!;
-							const selected = index === optionIndex;
-							const prefix = selected ? theme.fg("accent", "> ") : "  ";
-							const label = `${index + 1}. ${index === 0 ? withRecommended(option.label) : option.label}${option.isOther && editMode ? " ✎" : ""}`;
-							addWrappedWithPrefix(prefix, theme.fg(selected || (option.isOther && editMode) ? "accent" : "text", label));
-							if (option.description) addWrappedWithPrefix("     ", theme.fg("muted", option.description));
-						}
-						if (editMode) {
-							lines.push("");
-							addWrappedWithPrefix(" ", theme.fg("muted", "Your answer:"));
-							for (const line of editor.render(Math.max(1, renderWidth - 2))) lines.push(` ${line}`);
-						}
-						lines.push("");
-						addWrappedWithPrefix(" ", theme.fg("dim", editMode ? "Enter to submit • Esc to go back" : `↑↓ navigate • 1–${allOptions.length} or Enter to select • Esc to cancel`));
-						lines.push(theme.fg("accent", "─".repeat(renderWidth)));
-						cachedLines = lines;
-						return lines;
-					}
-
-					const abort = (): void => done(null);
-					if (signal?.aborted) abort();
-					else signal?.addEventListener("abort", abort, { once: true });
-
-					return {
-						render,
-						invalidate: () => { cachedLines = undefined; },
-						handleInput,
-						dispose: () => signal?.removeEventListener("abort", abort),
-					};
-				},
-			);
-
-			if (!result) {
-				return {
-					content: [{ type: "text" as const, text: "User cancelled question" }],
-					details: { question, options, answer: null } satisfies QuestionDetails,
-				};
-			}
+			const details = await askQuestion(params, ctx, signal);
 			return {
 				content: [{
 					type: "text" as const,
-					text: result.wasCustom ? `User wrote: ${result.answer}` : `User selected: ${result.index}. ${result.answer}`,
+					text: details.error
+						? `Error: ${details.error}`
+						: !details.answer
+							? "User cancelled question"
+							: details.wasCustom
+								? `User wrote: ${details.answer}`
+								: `User selected: ${details.selectedIndex}. ${details.answer}`,
 				}],
-				details: {
-					question,
-					options,
-					answer: result.answer,
-					wasCustom: result.wasCustom,
-					selectedIndex: result.index,
-				} satisfies QuestionDetails,
+				details,
 			};
 		},
-
-		renderCall(args, theme) {
-			let text = theme.fg("toolTitle", theme.bold("ask_question ")) + theme.fg("muted", args.question);
-			const options = Array.isArray(args.options) ? args.options : [];
-			if (options.length) {
-				const labels = options.map((option: QuestionOption) => option.label);
-				const numbered = [...labels, CUSTOM_OPTION_LABEL].map((option, index) => `${index + 1}. ${index === 0 ? withRecommended(option) : option}`);
-				text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
-			}
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, _options, theme) {
-			const details = result.details as QuestionDetails | undefined;
-			if (!details) {
-				const content = result.content[0];
-				return new Text(content?.type === "text" ? content.text : "", 0, 0);
-			}
-			if (details.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
-			if (details.answer === null) return new Text(theme.fg("warning", "Cancelled"), 0, 0);
-			if (details.wasCustom) {
-				return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "(wrote) ") + theme.fg("accent", details.answer), 0, 0);
-			}
-			const display = details.selectedIndex ? `${details.selectedIndex}. ${details.answer}` : details.answer;
-			return new Text(theme.fg("success", "✓ ") + theme.fg("accent", display), 0, 0);
-		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-ask-question",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Ask Pi users one interactive question with choices or a custom answer.",
   "keywords": [
     "pi-package",
@@ -14,18 +14,28 @@
   },
   "license": "MIT",
   "files": [
+    "dist",
     "extensions",
     "README.md",
     "LICENSE"
   ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.ts",
     "test:manual": "pi --no-extensions -e ./extensions/ask-question.ts --tools ask_question --no-session \"We need storage for a small team app. Before making changes, ask me to choose storage.\"",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/ask-question.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck src/*.ts extensions/ask-question.ts test/*.test.ts",
+    "prepack": "npm run build",
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.84.1",
-    "@earendil-works/pi-tui": ">=0.84.1",
     "typebox": "^1.3.15"
   },
   "repository": {