@mrclrchtr/supi-ask-user 1.3.1 → 1.4.0

package/src/ask-user.ts

@@ -1,140 +1,101 @@
-// `ask_user` extension entry point. Registers a single model-callable tool
-// for focused interactive decisions during an agent run. Holds the per-session
-// single-active-questionnaire lock and drives the rich overlay UI.
-//
-// Implementation modules:
-//   schema.ts           — external (LLM-facing) parameter schema
-//   normalize.ts        — validation + normalization into the shared internal model
-//   flow.ts             — shared questionnaire flow + concurrency lock
-//   ui-rich.ts          — overlay UI via ctx.ui.custom()
-//   ui-rich-render.ts   — overlay rendering helpers
-//   result.ts           — hybrid (content + details) result formatting
-//   render.ts           — custom renderCall / renderResult for the transcript
-
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { formatTitle, signalWaiting } from "@mrclrchtr/supi-core/api";
-import { ActiveQuestionnaireLock } from "./flow.ts";
 import { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
-import { renderAskUserCall, renderAskUserResult } from "./render.ts";
-import { buildErrorResult, buildResult, type HybridResult } from "./result.ts";
+import { type AskUserToolResult, buildErrorResult, buildResult } from "./render/result.ts";
+import { renderAskUserCall, renderAskUserResult } from "./render/transcript.ts";
+import { buildTreeSummaryLabel } from "./render/tree-summary.ts";
 import { type AskUserParams, AskUserParamsSchema } from "./schema.ts";
-import type { NormalizedQuestionnaire } from "./types.ts";
-import { type RichUiHost, runRichQuestionnaire } from "./ui/ui-rich.ts";
+import { ActiveQuestionnaireLock } from "./session/lock.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
+import type { AskUserToolDetails, NormalizedQuestionnaire } from "./types.ts";
+import { runQuestionnaire } from "./ui/choose-renderer.ts";
 
 const TOOL_NAME = "ask_user";
 const TOOL_LABEL = "Ask User";
 
-const TOOL_DESCRIPTION =
-  "Ask the user a focused decision question (or up to 4 grouped questions) when explicit user input is required to proceed safely. Use for clarifying intent, picking between options, prioritizing a short set of features, or confirming a destructive action — not for surveys or open-ended discovery. Questions are `choice` (with options; set `multi: true` for multi-select) or `text` (freeform input). Structured questions can add `recommendation`, `default`, `allowOther`, `allowDiscuss`, and option `preview` content.";
-
-const PROMPT_SNIPPET =
-  "ask_user — pause and request a focused decision (1-4 typed questions) when explicit user input is required to proceed, including rich choice and discuss flows";
-
-const PROMPT_GUIDELINES = [
-  "Use ask_user only for decisions that require explicit user input — never as a substitute for reading code or thinking through a problem.",
-  "Keep questionnaires bounded: 1-4 focused questions with short headers; prefer one decision per call when possible.",
-  'There are two question types: `choice` for picking from options (single-select by default; set `multi: true` for multi-select — use this instead of the now-removed `multichoice`) and `text` for freeform input. For yes/no questions, use `choice` with options `{value: "yes", label: "Yes"}` and `{value: "no", label: "No"}`.',
-  "Set `recommendation` when one option or a small set of options is clearly preferable, so the UI can surface that guidance.",
-  "Set `default` to pre-select a starting value or option; the user can accept it with a single keystroke. Use it for safe/common defaults, distinct from `recommendation` which highlights what you think is best.",
-  "Enable `allowOther` only when a custom answer is genuinely useful, and `allowDiscuss` only when the user may need to talk through the choice instead of deciding immediately.",
-  "Use `description` to explain what each option means — it wraps naturally and a few sentences is fine. Reserve `preview` for code, config, or diagrams that need dedicated rendering space in a side pane.",
-  "Do not call ask_user while another ask_user interaction is in flight — wait for the previous result before issuing another.",
-];
-
-/** Minimal ui subset needed by executeAskUser — extended with setTitle/notify from ExtensionUIContext. */
-interface ExtensionUi {
+export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "abort"> & {
   ui: {
-    custom?: RichUiHost["custom"];
+    custom?: unknown;
+    notify?(message: string, type?: "info" | "warning" | "error"): void;
     setWorkingVisible?(visible: boolean): void;
-    /** Set the terminal window/tab title. */
     setTitle?(title: string): void;
-    /** Show a notification to the user. */
-    notify?(message: string, type?: "info" | "warning" | "error"): void;
   };
-  /**
-   * Absolute path to the current working directory, available on the full
-   * ExtensionContext. Marked optional here to tolerate partial mocks.
-   */
-  cwd?: string;
-  hasUI: boolean;
-  abort(): void;
-}
+};
 
 export default function askUserExtension(pi: ExtensionAPI): void {
   const lock = new ActiveQuestionnaireLock();
 
-  pi.registerTool({
+  pi.registerTool<typeof AskUserParamsSchema, AskUserToolDetails>({
     name: TOOL_NAME,
     label: TOOL_LABEL,
-    description: TOOL_DESCRIPTION,
-    promptSnippet: PROMPT_SNIPPET,
-    promptGuidelines: PROMPT_GUIDELINES,
+    description: toolDescription,
+    promptSnippet,
+    promptGuidelines,
     parameters: AskUserParamsSchema,
     // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      return executeAskUser(
-        params as AskUserParams,
-        signal,
-        ctx as unknown as ExtensionUi,
-        lock,
-        pi,
-      );
+      return executeAskUser(params, signal, ctx, lock, pi);
     },
-    renderCall: (args, theme) => renderAskUserCall(args, theme as Theme),
-    renderResult: (result, _options, theme) =>
-      renderAskUserResult(
-        result as { details?: unknown; content: { type: string; text?: string }[] },
-        theme as Theme,
-      ) as unknown as Component,
+    renderCall: (args, theme) => renderAskUserCall(args, theme),
+    renderResult: (result, _options, theme) => renderAskUserResult(result, theme),
   });
 }
 
-// biome-ignore lint/complexity/useMaxParams: pi context + pi reference for appendEntry
-async function executeAskUser(
+// biome-ignore lint/complexity/useMaxParams: keep the execution boundary explicit for tests
+export async function executeAskUser(
   params: AskUserParams,
   signal: AbortSignal | undefined,
-  ctx: ExtensionUi,
+  ctx: AskUserExecutionContext,
   lock: ActiveQuestionnaireLock,
   pi: ExtensionAPI,
-): Promise<HybridResult> {
-  let normalized: NormalizedQuestionnaire;
+): Promise<AskUserToolResult> {
+  let questionnaire: NormalizedQuestionnaire;
   try {
-    normalized = normalizeQuestionnaire(params);
-  } catch (err) {
-    if (err instanceof AskUserValidationError) return buildErrorResult(`Error: ${err.message}`);
-    throw err;
+    questionnaire = normalizeQuestionnaire(params);
+  } catch (error) {
+    if (error instanceof AskUserValidationError) {
+      return buildErrorResult(`Error: ${error.message}`);
+    }
+    throw error;
   }
+
   if (!ctx.hasUI) {
     return buildErrorResult(
-      "Error: ask_user requires interactive UI but the current session has none.",
+      "Error: ask_user requires an interactive UI session. No user-facing UI is available in the current mode.",
     );
   }
   if (!lock.acquire()) {
     return buildErrorResult(
-      "Error: another ask_user interaction is already in flight. Wait for it to complete before calling ask_user again.",
+      "Error: another ask_user form is already in flight. Wait for it to complete before calling ask_user again.",
     );
   }
+
   signalAttention(ctx);
   pi.events.emit("supi:ask-user:start", { source: "supi-ask-user" });
+
   try {
-    // Hide the built-in working loader so it doesn't compete with the overlay.
     ctx.ui.setWorkingVisible?.(false);
-    const result = await driveQuestionnaire(normalized, signal, ctx);
-    if (
-      result.details.terminalState !== "submitted" &&
-      result.details.terminalState !== "skipped"
-    ) {
+    const outcome = await runQuestionnaire(questionnaire, {
+      ui: {
+        custom: asFunction(ctx.ui.custom),
+        notify: ctx.ui.notify,
+      },
+      signal,
+    });
+
+    if (outcome === "unsupported") {
+      return buildErrorResult(
+        "Error: ask_user requires a TUI with custom overlay support. Do not use ask_user in non-interactive or degraded UI sessions.",
+      );
+    }
+
+    if (outcome.status === "cancelled" || outcome.status === "aborted") {
       ctx.abort();
     }
-    // Append a tree-friendly custom entry so /tree shows a readable
-    // summary (question headers) instead of raw JSON tool-call arguments.
-    // Custom entries are hidden in the default tree filter, visible in
-    // "all" mode (Ctrl+O).
-    pi.appendEntry(treeSummaryLabel(normalized));
-    return result;
+
+    pi.appendEntry(buildTreeSummaryLabel(questionnaire));
+    return buildResult(questionnaire, outcome);
   } finally {
-    // Restore the working loader regardless of how the overlay closed.
     ctx.ui.setWorkingVisible?.(true);
     pi.events.emit("supi:ask-user:end", { source: "supi-ask-user" });
     restoreTerminalTitle(ctx, pi);
@@ -142,50 +103,23 @@ async function executeAskUser(
   }
 }
 
-/** Set terminal title and play alert bell to signal the user needs to respond. */
-function signalAttention(ctx: ExtensionUi): void {
-  signalWaiting(ctx, `pi — waiting for your input`);
+function signalAttention(ctx: AskUserExecutionContext): void {
+  signalWaiting(ctx, "pi — waiting for your input");
 }
 
-/** Restore the terminal title to pi's native format (session name + cwd). */
-function restoreTerminalTitle(ctx: ExtensionUi, pi: ExtensionAPI): void {
+function restoreTerminalTitle(ctx: AskUserExecutionContext, pi: ExtensionAPI): void {
   ctx.ui.setTitle?.(formatTitle(pi.getSessionName(), ctx.cwd));
 }
 
-/** Build a concise custom-entry label readable in the /tree "all" filter. */
-function treeSummaryLabel(q: NormalizedQuestionnaire): string {
-  const count = q.questions.length;
-  const s = count === 1 ? "" : "s";
-  const headers = q.questions.map((q) => q.header).join(", ");
-  if (headers.length > 70) {
-    return `ask_user · ${count} question${s} · ${headers.slice(0, 67)}...`;
-  }
-  return `ask_user · ${count} question${s} · ${headers}`;
-}
-
-async function driveQuestionnaire(
-  questionnaire: NormalizedQuestionnaire,
-  signal: AbortSignal | undefined,
-  ctx: ExtensionUi,
-): Promise<HybridResult> {
-  const questions = questionnaire.questions;
-  if (typeof ctx.ui.custom !== "function") {
-    return buildErrorResult(
-      "Error: ask_user requires a TUI with custom overlay support. Do not use ask_user in non-interactive or degraded UI sessions.",
-    );
-  }
-  const richHost: RichUiHost = { custom: ctx.ui.custom.bind(ctx.ui) };
-  const outcome = await runRichQuestionnaire(questionnaire, { ui: richHost, signal });
-  if (outcome === "unsupported") {
-    return buildErrorResult(
-      "Error: ask_user requires a TUI with custom overlay support. Do not use ask_user in non-interactive or degraded UI sessions.",
-    );
-  }
-  return buildResult(questions, outcome);
+function asFunction<T extends (...args: never[]) => unknown>(value: unknown): T | undefined {
+  return typeof value === "function" ? (value as T) : undefined;
 }
 
-export { ActiveQuestionnaireLock, QuestionnaireFlow } from "./flow.ts";
-// Re-exports used by tests.
 export { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
-export { buildResult } from "./result.ts";
-export { PROMPT_GUIDELINES as askUserPromptGuidelines, PROMPT_SNIPPET as askUserPromptSnippet };
+export { buildErrorResult, buildResult } from "./render/result.ts";
+export { AskUserController } from "./session/controller.ts";
+export { ActiveQuestionnaireLock } from "./session/lock.ts";
+export {
+  promptGuidelines as askUserPromptGuidelines,
+  promptSnippet as askUserPromptSnippet,
+} from "./tool/guidance.ts";

package/src/index.ts

@@ -1 +1,23 @@
-export { default } from "./ask-user.ts";
+export type {
+  Answer,
+  AskUserDetails,
+  AskUserErrorDetails,
+  AskUserOutcome,
+  AskUserStatus,
+  AskUserToolDetails,
+  ChoiceAnswer,
+  CustomAnswer,
+  NormalizedChoiceQuestion,
+  NormalizedQuestion,
+  NormalizedQuestionnaire,
+  NormalizedTextQuestion,
+  TextAnswer,
+} from "./api.ts";
+export {
+  ActiveQuestionnaireLock,
+  AskUserController,
+  AskUserParamsSchema,
+  AskUserValidationError,
+  default,
+  normalizeQuestionnaire,
+} from "./api.ts";

package/src/normalize.ts

@@ -1,13 +1,18 @@
-// Validates raw `ask_user` parameters and lowers them into the shared internal
-// questionnaire model. Both UI paths and result formatting consume only this
-// normalized model, so the overlay and dialog flows cannot drift apart.
+// Validation and normalization for ask_user tool calls.
 
-import type { AskUserParams, ExternalQuestion } from "./schema.ts";
+import type {
+  AskUserParams,
+  ExternalChoiceQuestion,
+  ExternalQuestion,
+  ExternalTextQuestion,
+} from "./schema.ts";
 import {
+  ASK_USER_LIMITS,
+  type NormalizedChoiceQuestion,
   type NormalizedOption,
   type NormalizedQuestion,
   type NormalizedQuestionnaire,
-  QUESTION_LIMITS,
+  type NormalizedTextQuestion,
 } from "./types.ts";
 
 export class AskUserValidationError extends Error {
@@ -18,212 +23,218 @@ export class AskUserValidationError extends Error {
 }
 
 export function normalizeQuestionnaire(params: AskUserParams): NormalizedQuestionnaire {
-  validateQuestionnaireShape(params);
-  return {
-    questions: params.questions.map((q) => normalizeQuestion(q)),
-    allowSkip: params.allowSkip ?? false,
-  };
-}
-
-function validateQuestionnaireShape(params: AskUserParams): void {
-  const count = params.questions.length;
-  if (count < QUESTION_LIMITS.minQuestions || count > QUESTION_LIMITS.maxQuestions) {
-    throw new AskUserValidationError(
-      `ask_user supports ${QUESTION_LIMITS.minQuestions}-${QUESTION_LIMITS.maxQuestions} questions only (got ${count}).`,
-    );
+  validateQuestionCount(params.questions.length);
+  const title = trimOptional(params.title);
+  const intro = trimOptional(params.intro);
+  if (title && title.length > ASK_USER_LIMITS.maxTitleLength) {
+    throw new AskUserValidationError(`title exceeds ${ASK_USER_LIMITS.maxTitleLength} characters.`);
   }
+  if (intro && intro.length > ASK_USER_LIMITS.maxIntroLength) {
+    throw new AskUserValidationError(`intro exceeds ${ASK_USER_LIMITS.maxIntroLength} characters.`);
+  }
+
   const seen = new Set<string>();
-  for (const q of params.questions) {
-    const questionId = q.id.trim();
-    if (questionId.length === 0) continue;
-    if (seen.has(questionId)) {
+  const questions = params.questions.map((question) => {
+    const normalized = normalizeQuestion(question);
+    if (seen.has(normalized.id)) {
       throw new AskUserValidationError(
-        `Duplicate question id "${questionId}" — question ids must be unique within a questionnaire.`,
+        `Duplicate question id "${normalized.id}" — ids must be unique within one form.`,
       );
     }
-    seen.add(questionId);
-  }
+    seen.add(normalized.id);
+    return normalized;
+  });
+
+  return {
+    ...(title ? { title } : {}),
+    ...(intro ? { intro } : {}),
+    questions,
+    allowPartialSubmit: params.allowPartialSubmit ?? false,
+    allowDiscuss: params.allowDiscuss ?? false,
+  };
 }
 
-function normalizeQuestion(q: ExternalQuestion): NormalizedQuestion {
-  validateCommonFields(q);
-  switch (q.type) {
-    case "choice":
-      return normalizeChoice(q);
-    case "text":
-      return normalizeText(q);
-  }
+function normalizeQuestion(question: ExternalQuestion): NormalizedQuestion {
+  validateCommonFields(question);
+  return question.type === "choice" ? normalizeChoice(question) : normalizeText(question);
 }
 
-function validateCommonFields(q: ExternalQuestion): void {
-  if (q.id.trim().length === 0) {
-    throw new AskUserValidationError("Question id must be a non-empty string.");
+function validateQuestionCount(count: number): void {
+  if (count < ASK_USER_LIMITS.minQuestions || count > ASK_USER_LIMITS.maxQuestions) {
+    throw new AskUserValidationError(
+      `ask_user supports ${ASK_USER_LIMITS.minQuestions}-${ASK_USER_LIMITS.maxQuestions} questions only (got ${count}).`,
+    );
   }
-  if (q.header.trim().length === 0) {
-    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty header.`);
+}
+
+function validateCommonFields(question: ExternalQuestion): void {
+  const id = question.id.trim();
+  const header = question.header.trim();
+  const prompt = question.prompt.trim();
+
+  if (!id) throw new AskUserValidationError("Question id must be a non-empty string.");
+  if (!header) {
+    throw new AskUserValidationError(`Question "${question.id}" must include a non-empty header.`);
   }
-  if (q.header.length > QUESTION_LIMITS.maxHeaderLength) {
+  if (header.length > ASK_USER_LIMITS.maxHeaderLength) {
     throw new AskUserValidationError(
-      `Question "${q.id}" header exceeds ${QUESTION_LIMITS.maxHeaderLength} characters.`,
+      `Question "${question.id}" header exceeds ${ASK_USER_LIMITS.maxHeaderLength} characters.`,
     );
   }
-  if (q.prompt.trim().length === 0) {
-    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty prompt.`);
+  if (!prompt) {
+    throw new AskUserValidationError(`Question "${question.id}" must include a non-empty prompt.`);
   }
-  if (q.prompt.length > QUESTION_LIMITS.maxPromptLength) {
+  if (prompt.length > ASK_USER_LIMITS.maxPromptLength) {
     throw new AskUserValidationError(
-      `Question "${q.id}" prompt exceeds ${QUESTION_LIMITS.maxPromptLength} characters.`,
+      `Question "${question.id}" prompt exceeds ${ASK_USER_LIMITS.maxPromptLength} characters.`,
     );
   }
 }
 
-function normalizeChoice(q: {
-  type: "choice";
-  id: string;
-  header: string;
-  prompt: string;
-  required?: boolean;
-  multi?: boolean;
-  options: { value: string; label: string; description?: string; preview?: string }[];
-  allowOther?: boolean;
-  allowDiscuss?: boolean;
-  recommendation?: string | string[];
-  default?: string | string[];
-}): NormalizedQuestion {
-  const id = q.id.trim();
-  const options = normalizeStructuredOptions(id, q.options);
-  const multi = q.multi ?? false;
-  const recommendation = q.recommendation;
-  const defaultValue = q.default;
-
-  validateRecDefaultShape(id, recommendation, multi, "recommendation");
-  validateRecDefaultShape(id, defaultValue, multi, "default");
+function normalizeChoice(question: ExternalChoiceQuestion): NormalizedChoiceQuestion {
+  const options = normalizeOptions(question.id.trim(), question.options);
+  const multi = question.multi ?? false;
+  const allowOther = question.allowOther ?? false;
+  if (multi && allowOther) {
+    throw new AskUserValidationError(
+      `choice question "${question.id}" cannot use allowOther together with multi-select.`,
+    );
+  }
+
+  validateSelectionShape(question.id, question.recommendation, multi, "recommendation");
+  validateSelectionShape(question.id, question.initial, multi, "initial");
 
   return {
-    id,
-    header: q.header,
+    id: question.id.trim(),
+    header: question.header.trim(),
+    prompt: question.prompt.trim(),
+    required: question.required ?? true,
     type: "choice",
-    prompt: q.prompt,
-    required: q.required ?? true,
-    multi,
     options,
-    allowOther: q.allowOther ?? false,
-    allowDiscuss: q.allowDiscuss ?? false,
-    recommendedIndexes: resolveRecDefault(id, options, recommendation, multi, "recommendation"),
-    defaultIndexes: resolveRecDefault(id, options, defaultValue, multi, "default"),
+    multi,
+    allowOther,
+    recommendedIndexes: resolveIndexes({
+      questionId: question.id,
+      options,
+      value: question.recommendation,
+      multi,
+      kind: "recommendation",
+    }),
+    initialIndexes: resolveIndexes({
+      questionId: question.id,
+      options,
+      value: question.initial,
+      multi,
+      kind: "initial",
+    }),
   };
 }
 
-function validateRecDefaultShape(
-  questionId: string,
-  value: string | string[] | undefined,
-  multi: boolean,
-  kind: string,
-): void {
-  if (value === undefined) return;
-  if (!multi && Array.isArray(value)) {
-    throw new AskUserValidationError(
-      `single-select question "${questionId}" ${kind} must be a string, not an array.`,
-    );
-  }
-  if (multi && !Array.isArray(value)) {
+function normalizeText(question: ExternalTextQuestion): NormalizedTextQuestion {
+  const placeholder = trimOptional(question.placeholder);
+  if (placeholder && placeholder.length > ASK_USER_LIMITS.maxPlaceholderLength) {
     throw new AskUserValidationError(
-      `multi-select question "${questionId}" ${kind} must be an array, not a string.`,
+      `Question "${question.id}" placeholder exceeds ${ASK_USER_LIMITS.maxPlaceholderLength} characters.`,
     );
   }
-}
 
-function normalizeText(q: {
-  id: string;
-  header: string;
-  prompt: string;
-  required?: boolean;
-  default?: string;
-}): NormalizedQuestion {
   return {
-    id: q.id.trim(),
-    header: q.header,
+    id: question.id.trim(),
+    header: question.header.trim(),
+    prompt: question.prompt.trim(),
+    required: question.required ?? true,
     type: "text",
-    prompt: q.prompt,
-    required: q.required ?? true,
-    options: [],
-    ...(q.default !== undefined ? { default: q.default.trim() } : {}),
+    ...(question.initial !== undefined ? { initial: question.initial } : {}),
+    ...(placeholder ? { placeholder } : {}),
   };
 }
 
-function normalizeStructuredOptions(
+function normalizeOptions(
   questionId: string,
-  options: { value: string; label: string; description?: string; preview?: string }[],
+  options: ExternalChoiceQuestion["options"],
 ): NormalizedOption[] {
-  const optionCount = options.length;
   if (
-    optionCount < QUESTION_LIMITS.minChoiceOptions ||
-    optionCount > QUESTION_LIMITS.maxChoiceOptions
+    options.length < ASK_USER_LIMITS.minChoiceOptions ||
+    options.length > ASK_USER_LIMITS.maxChoiceOptions
   ) {
     throw new AskUserValidationError(
-      `choice question "${questionId}" must have ${QUESTION_LIMITS.minChoiceOptions}-${QUESTION_LIMITS.maxChoiceOptions} options (got ${optionCount}).`,
+      `choice question "${questionId}" must have ${ASK_USER_LIMITS.minChoiceOptions}-${ASK_USER_LIMITS.maxChoiceOptions} options (got ${options.length}).`,
     );
   }
-  const seenValues = new Set<string>();
-  return options.map((opt) => {
-    const value = opt.value.trim();
-    if (value.length === 0 || opt.label.trim().length === 0) {
+
+  const seen = new Set<string>();
+  return options.map((option) => {
+    const value = option.value.trim();
+    const label = option.label.trim();
+    if (!value || !label) {
       throw new AskUserValidationError(
         `choice question "${questionId}" has an option with empty value or label.`,
       );
     }
-    if (seenValues.has(value)) {
+    if (seen.has(value)) {
       throw new AskUserValidationError(
         `choice question "${questionId}" has duplicate option value "${value}".`,
       );
     }
-    seenValues.add(value);
+    seen.add(value);
     return {
       value,
-      label: opt.label,
-      description: opt.description,
-      preview: opt.preview,
+      label,
+      description: trimOptional(option.description),
+      preview: trimOptional(option.preview),
     };
   });
 }
 
-// biome-ignore lint/complexity/useMaxParams: five distinct positional params are cleaner than a non-reusable options object for this internal helper
-function resolveRecDefault(
+function validateSelectionShape(
   questionId: string,
-  options: NormalizedOption[],
   value: string | string[] | undefined,
   multi: boolean,
-  kind: "recommendation" | "default",
-): number[] {
-  if (value === undefined) return [];
-  const verb = kind === "recommendation" ? "recommends" : "defaults to";
-  if (!multi) {
-    const trimmed = (value as string).trim();
-    const idx = options.findIndex((opt) => opt.value === trimmed);
-    if (idx < 0) {
-      throw new AskUserValidationError(
-        `choice question "${questionId}" ${verb} "${trimmed}", which is not one of its option values.`,
-      );
-    }
-    return [idx];
+  kind: "recommendation" | "initial",
+): void {
+  if (value === undefined) return;
+  if (multi && !Array.isArray(value)) {
+    throw new AskUserValidationError(
+      `multi-select question "${questionId}" ${kind} must be an array, not a string.`,
+    );
   }
-  const values = value as string[];
-  if (values.length === 0) return [];
+  if (!multi && Array.isArray(value)) {
+    throw new AskUserValidationError(
+      `single-select question "${questionId}" ${kind} must be a string, not an array.`,
+    );
+  }
+}
+
+function resolveIndexes(args: {
+  questionId: string;
+  options: NormalizedOption[];
+  value: string | string[] | undefined;
+  multi: boolean;
+  kind: "recommendation" | "initial";
+}): number[] {
+  const { questionId, options, value, multi, kind } = args;
+  if (value === undefined) return [];
+  const values = multi ? (value as string[]) : [value as string];
   const seen = new Set<string>();
-  return values.map((v) => {
-    const trimmed = v.trim();
+  return values.map((entry: string) => {
+    const trimmed = entry.trim();
     if (seen.has(trimmed)) {
       throw new AskUserValidationError(
-        `choice question "${questionId}" has duplicate ${kind === "recommendation" ? "recommended" : "default"} value "${trimmed}".`,
+        `choice question "${questionId}" has duplicate ${kind} value "${trimmed}".`,
       );
     }
     seen.add(trimmed);
-    const idx = options.findIndex((opt) => opt.value === trimmed);
-    if (idx < 0) {
+    const index = options.findIndex((option) => option.value === trimmed);
+    if (index < 0) {
       throw new AskUserValidationError(
-        `choice question "${questionId}" ${verb} "${trimmed}", which is not one of its option values.`,
+        `choice question "${questionId}" ${kind} value "${trimmed}" does not match any option value.`,
       );
     }
-    return idx;
+    return index;
   });
 }
+
+function trimOptional(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}