@mrclrchtr/supi-ask-user 0.1.0 → 0.2.0

package/src/format.ts

@@ -0,0 +1,66 @@
+// Shared formatting helpers used by the overlay UI and result rendering.
+// Keeps summary/review formatting in one place so the overlay, transcript
+// renderer, and tool-content summary cannot accidentally diverge.
+
+import type { Answer, NormalizedQuestion } from "./types.ts";
+
+export const OTHER_LABEL = "Other answer";
+export const DISCUSS_LABEL = "Discuss instead";
+export const SUBMIT_SELECTIONS_LABEL = "Submit selections";
+export const NOTE_MARKER = "✎";
+
+export function decorateOption(label: string, recommended: boolean): string {
+  if (!recommended) return label;
+  if (label.trimEnd().toLowerCase().endsWith("(recommended)")) return label;
+  return `${label} (recommended)`;
+}
+
+// formatSummaryBody and formatReviewLines must be kept in sync —
+// when adding a new answer source, update both functions.
+export function formatSummaryBody(question: NormalizedQuestion, answer: Answer): string {
+  switch (answer.source) {
+    case "choice":
+      return answer.selections
+        .map((selection) => {
+          const label = question.options[selection.optionIndex]?.label ?? selection.value;
+          return withNote(label, selection.note);
+        })
+        .join("; ");
+    case "other":
+      return `Other — ${answer.value}`;
+    case "discuss":
+      return answer.value ? `Discuss — ${answer.value}` : "Discuss";
+    case "text":
+      return answer.value;
+  }
+}
+
+export function formatReviewBody(question: NormalizedQuestion, answer: Answer): string {
+  return formatReviewLines(question, answer).join("; ");
+}
+
+export function formatReviewLines(question: NormalizedQuestion, answer: Answer): string[] {
+  switch (answer.source) {
+    case "choice":
+      if (answer.selections.length === 0) return ["(no selections)"];
+      return answer.selections.map((selection) => {
+        const label = question.options[selection.optionIndex]?.label ?? selection.value;
+        return withNote(label, selection.note);
+      });
+    case "other":
+      return [`Other: ${answer.value}`];
+    case "discuss":
+      return [answer.value ? `Discuss: ${answer.value}` : "Discuss"];
+    case "text":
+      return [answer.value];
+  }
+}
+
+export function formatReviewLine(question: NormalizedQuestion, answer: Answer | undefined): string {
+  if (!answer) return "(no answer)";
+  return formatReviewBody(question, answer);
+}
+
+function withNote(body: string, note: string | undefined): string {
+  return note ? `${body} — ${note}` : body;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./ask-user.ts";

package/src/normalize.ts

@@ -0,0 +1,229 @@
+// 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.
+
+import type { AskUserParams, ExternalQuestion } from "./schema.ts";
+import {
+  type NormalizedOption,
+  type NormalizedQuestion,
+  type NormalizedQuestionnaire,
+  QUESTION_LIMITS,
+} from "./types.ts";
+
+export class AskUserValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AskUserValidationError";
+  }
+}
+
+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}).`,
+    );
+  }
+  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)) {
+      throw new AskUserValidationError(
+        `Duplicate question id "${questionId}" — question ids must be unique within a questionnaire.`,
+      );
+    }
+    seen.add(questionId);
+  }
+}
+
+function normalizeQuestion(q: ExternalQuestion): NormalizedQuestion {
+  validateCommonFields(q);
+  switch (q.type) {
+    case "choice":
+      return normalizeChoice(q);
+    case "text":
+      return normalizeText(q);
+  }
+}
+
+function validateCommonFields(q: ExternalQuestion): void {
+  if (q.id.trim().length === 0) {
+    throw new AskUserValidationError("Question id must be a non-empty string.");
+  }
+  if (q.header.trim().length === 0) {
+    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty header.`);
+  }
+  if (q.header.length > QUESTION_LIMITS.maxHeaderLength) {
+    throw new AskUserValidationError(
+      `Question "${q.id}" header exceeds ${QUESTION_LIMITS.maxHeaderLength} characters.`,
+    );
+  }
+  if (q.prompt.trim().length === 0) {
+    throw new AskUserValidationError(`Question "${q.id}" must include a non-empty prompt.`);
+  }
+  if (q.prompt.length > QUESTION_LIMITS.maxPromptLength) {
+    throw new AskUserValidationError(
+      `Question "${q.id}" prompt exceeds ${QUESTION_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");
+
+  return {
+    id,
+    header: q.header,
+    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"),
+  };
+}
+
+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)) {
+    throw new AskUserValidationError(
+      `multi-select question "${questionId}" ${kind} must be an array, not a string.`,
+    );
+  }
+}
+
+function normalizeText(q: {
+  id: string;
+  header: string;
+  prompt: string;
+  required?: boolean;
+  default?: string;
+}): NormalizedQuestion {
+  return {
+    id: q.id.trim(),
+    header: q.header,
+    type: "text",
+    prompt: q.prompt,
+    required: q.required ?? true,
+    options: [],
+    ...(q.default !== undefined ? { default: q.default.trim() } : {}),
+  };
+}
+
+function normalizeStructuredOptions(
+  questionId: string,
+  options: { value: string; label: string; description?: string; preview?: string }[],
+): NormalizedOption[] {
+  const optionCount = options.length;
+  if (
+    optionCount < QUESTION_LIMITS.minChoiceOptions ||
+    optionCount > QUESTION_LIMITS.maxChoiceOptions
+  ) {
+    throw new AskUserValidationError(
+      `choice question "${questionId}" must have ${QUESTION_LIMITS.minChoiceOptions}-${QUESTION_LIMITS.maxChoiceOptions} options (got ${optionCount}).`,
+    );
+  }
+  const seenValues = new Set<string>();
+  return options.map((opt) => {
+    const value = opt.value.trim();
+    if (value.length === 0 || opt.label.trim().length === 0) {
+      throw new AskUserValidationError(
+        `choice question "${questionId}" has an option with empty value or label.`,
+      );
+    }
+    if (seenValues.has(value)) {
+      throw new AskUserValidationError(
+        `choice question "${questionId}" has duplicate option value "${value}".`,
+      );
+    }
+    seenValues.add(value);
+    return {
+      value,
+      label: opt.label,
+      description: opt.description,
+      preview: opt.preview,
+    };
+  });
+}
+
+// biome-ignore lint/complexity/useMaxParams: five distinct positional params are cleaner than a non-reusable options object for this internal helper
+function resolveRecDefault(
+  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];
+  }
+  const values = value as string[];
+  if (values.length === 0) return [];
+  const seen = new Set<string>();
+  return values.map((v) => {
+    const trimmed = v.trim();
+    if (seen.has(trimmed)) {
+      throw new AskUserValidationError(
+        `choice question "${questionId}" has duplicate ${kind === "recommendation" ? "recommended" : "default"} value "${trimmed}".`,
+      );
+    }
+    seen.add(trimmed);
+    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;
+  });
+}

package/{ui-rich-render-editor.ts → src/render/ui-rich-render-editor.ts}

@@ -1,9 +1,9 @@
 // Editor pane rendering helpers for the rich overlay.
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import type { Editor } from "@mariozechner/pi-tui";
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { OverlayRenderState } from "./ui-rich-render.ts";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Editor, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { RenderEnv } from "./ui-rich-render-env.ts";
+import type { OverlayRenderState } from "./ui-rich-render-types.ts";
 
 export function editorCaption(state: OverlayRenderState): string {
   if (state.subMode === "other-input") return "Other answer";
@@ -12,8 +12,14 @@ export function editorCaption(state: OverlayRenderState): string {
   return "Answer";
 }
 
+/** Whether the editor should render in a separate pane (split-view right side)
+ *  rather than inline within the option rows. */
 export function usesSeparateEditorPane(state: OverlayRenderState): boolean {
-  return state.subMode === "note-input";
+  return (
+    state.subMode === "note-input" ||
+    state.subMode === "other-input" ||
+    state.subMode === "discuss-input"
+  );
 }
 
 export function renderEditorPane(
@@ -29,17 +35,13 @@ export function renderEditorPane(
   return out;
 }
 
-// biome-ignore lint/complexity/useMaxParams: helper mirrors render context
-export function renderEditorBlock(
-  add: (text: string) => void,
-  lines: string[],
-  theme: Theme,
-  editor: Editor,
-  width: number,
-  caption: string,
-): void {
-  add(theme.fg("muted", ` ${caption}:`));
-  for (const line of editor.render(width - 2)) lines.push(` ${truncateToWidth(line, width - 1)}`);
+export function renderEditorBlock(env: RenderEnv, caption: string): string[] {
+  const out: string[] = [];
+  out.push(env.theme.fg("muted", ` ${caption}:`));
+  for (const line of env.editor.render(env.width - 2)) {
+    out.push(` ${truncateToWidth(line, env.width - 1)}`);
+  }
+  return out;
 }
 
 export function padRight(text: string, width: number): string {

package/src/render/ui-rich-render-env.ts

@@ -0,0 +1,15 @@
+// Shared rendering context for the rich overlay questionnaire UI.
+// Bundles the common parameters so individual helpers stay within param limits.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Editor } from "@earendil-works/pi-tui";
+import type { QuestionnaireFlow } from "../flow.ts";
+import type { OverlayRenderState } from "./ui-rich-render-types.ts";
+
+export interface RenderEnv {
+  width: number;
+  theme: Theme;
+  flow: QuestionnaireFlow;
+  state: OverlayRenderState;
+  editor: Editor;
+}

package/src/render/ui-rich-render-footer.ts

@@ -0,0 +1,55 @@
+// Footer help text generation for the rich overlay questionnaire UI.
+// Extracted from ui-rich-render.ts to stay within Biome's per-file line limit.
+
+import type { QuestionnaireFlow } from "../flow.ts";
+import type { NormalizedChoiceQuestion } from "../types.ts";
+import { isEditorMode, selectedIndexesForQuestion } from "../ui/ui-rich-state.ts";
+import { currentNote, currentRowSupportsNotes } from "./ui-rich-render-notes.ts";
+import type { OverlayRenderState } from "./ui-rich-render-types.ts";
+
+export function footerHelp(flow: QuestionnaireFlow, state: OverlayRenderState): string {
+  if (state.subMode === "text-input") {
+    const question = flow.currentQuestion;
+    const parts = ["Enter to submit"];
+    if (question && !question.required) parts.push("Esc skip question");
+    else parts.push("Esc to cancel");
+    if (flow.showSkip) parts.push("Ctrl-S skip");
+    return parts.join(" • ");
+  }
+  if (isEditorMode(state.subMode)) return "Enter to submit • Esc to go back";
+  if (flow.currentMode === "reviewing") {
+    const base = "Enter to submit • ←/Shift-Tab to revise • Esc to cancel";
+    return flow.showSkip ? `${base} • s to skip` : base;
+  }
+  const question = flow.currentQuestion;
+  if (!question || question.type === "text") {
+    const base = "Esc cancel";
+    return flow.showSkip ? `${base} • s to skip` : base;
+  }
+  return structuredFooterHelp(flow, state, question);
+}
+
+function structuredFooterHelp(
+  flow: QuestionnaireFlow,
+  state: OverlayRenderState,
+  question: NormalizedChoiceQuestion,
+): string {
+  const canGoBack = flow.currentIndex > 0;
+  const canAdvance =
+    flow.allRequiredAnswered() || (!question.required && !flow.hasAnswer(question.id));
+  const parts = ["↑↓ navigate"];
+  if (question.multi) {
+    parts.push("Space toggle");
+    if (selectedIndexesForQuestion(flow, state, question).length > 0) parts.push("Enter submit");
+  } else {
+    parts.push("Enter confirm/select");
+  }
+  if (currentRowSupportsNotes(question, state)) {
+    parts.push(currentNote(flow, state, question) ? "n edit note" : "n add note");
+  }
+  if (canGoBack) parts.push("←/Shift-Tab back");
+  if (canAdvance) parts.push("→/Tab next");
+  if (flow.showSkip) parts.push("s skip");
+  parts.push("Esc cancel");
+  return parts.join(" • ");
+}

package/src/render/ui-rich-render-markdown.ts

@@ -0,0 +1,33 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, highlightCode } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
+
+export interface RenderMarkdownOptions {
+  paddingX?: number;
+  defaultColor?: "text" | "muted" | "dim";
+}
+
+export function renderMarkdown(
+  text: string,
+  width: number,
+  theme: Theme,
+  options: RenderMarkdownOptions = {},
+): string[] {
+  const { paddingX = 1, defaultColor = "text" } = options;
+  const markdownTheme = getMarkdownTheme();
+  markdownTheme.highlightCode = (code: string, lang?: string) => {
+    try {
+      return highlightCode(code, lang);
+    } catch {
+      return code.split("\n").map((line) => markdownTheme.codeBlock(line));
+    }
+  };
+  const markdown = new Markdown(text, paddingX, 0, markdownTheme, {
+    color: (text: string) => theme.fg(defaultColor, text),
+  });
+  return markdown.render(width);
+}
+
+export function renderMarkdownPreview(preview: string, width: number, theme: Theme): string[] {
+  return renderMarkdown(preview, width, theme);
+}

package/{ui-rich-render-notes.ts → src/render/ui-rich-render-notes.ts}

@@ -1,10 +1,10 @@
 // Note-related rendering helpers for the rich overlay.
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import type { QuestionnaireFlow } from "./flow.ts";
-import type { MultiSelection, NormalizedQuestion, NormalizedStructuredQuestion } from "./types.ts";
-import type { OverlayRenderState } from "./ui-rich-render.ts";
-import { type InteractiveRow, interactiveRows } from "./ui-rich-state.ts";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { QuestionnaireFlow } from "../flow.ts";
+import type { NormalizedQuestion, NormalizedStructuredQuestion, Selection } from "../types.ts";
+import { type InteractiveRow, interactiveRows } from "../ui/ui-rich-state.ts";
+import type { OverlayRenderState } from "./ui-rich-render-types.ts";
 
 export function currentNote(
   flow: Pick<QuestionnaireFlow, "getAnswer">,
@@ -14,8 +14,7 @@ export function currentNote(
   if (!question || question.type === "text") return undefined;
   const row = interactiveRows(question)[state.selectedIndex];
   if (!row || row.kind !== "option") return undefined;
-  if (question.type === "multichoice")
-    return noteForMultiOption(flow, state, question, row.optionIndex);
+  if (question.multi) return noteForMultiOption(flow, state, question, row.optionIndex);
   return noteForSingle(flow, state, question);
 }
 
@@ -36,15 +35,14 @@ export function visibleNoteMarker(args: {
   active: boolean;
 }): boolean {
   const { flow, state, question, row, active } = args;
-  if (question.type === "multichoice")
-    return !!noteForMultiOption(flow, state, question, row.optionIndex);
+  if (question.multi) return !!noteForMultiOption(flow, state, question, row.optionIndex);
   return active && !!noteForSingle(flow, state, question);
 }
 
 export function noteForSingle(
   flow: Pick<QuestionnaireFlow, "getAnswer">,
   state: Pick<OverlayRenderState, "stagedSingleNotes">,
-  question: Exclude<NormalizedStructuredQuestion, { type: "multichoice" }>,
+  question: NormalizedStructuredQuestion,
 ): string | undefined {
   return state.stagedSingleNotes.get(question.id) ?? storedSingleNote(flow.getAnswer(question.id));
 }
@@ -52,36 +50,31 @@ export function noteForSingle(
 function storedSingleNote(
   answer: ReturnType<Pick<QuestionnaireFlow, "getAnswer">["getAnswer"]>,
 ): string | undefined {
-  if (!answer) return undefined;
-  if (answer.source === "option" || answer.source === "yesno") return answer.note;
-  return undefined;
+  if (!answer || answer.source !== "choice") return undefined;
+  return answer.selections[0]?.note;
 }
 
 export function noteForMultiOption(
   flow: Pick<QuestionnaireFlow, "getAnswer">,
   state: Pick<OverlayRenderState, "stagedMultiNotes">,
-  question: Extract<NormalizedStructuredQuestion, { type: "multichoice" }>,
+  question: NormalizedStructuredQuestion,
   optionIndex: number,
 ): string | undefined {
+  const answer = flow.getAnswer(question.id);
+  if (answer?.source === "other" || answer?.source === "discuss") return undefined;
   const staged = state.stagedMultiNotes.get(question.id)?.get(optionIndex);
   if (staged !== undefined) return staged;
-  return storedMultiSelections(flow.getAnswer(question.id)).find(
-    (selection) => selection.optionIndex === optionIndex,
-  )?.note;
+  return storedMultiSelections(answer).find((selection) => selection.optionIndex === optionIndex)
+    ?.note;
 }
 
 function storedMultiSelections(
   answer: ReturnType<Pick<QuestionnaireFlow, "getAnswer">["getAnswer"]>,
-): MultiSelection[] {
-  if (!answer || answer.source !== "options") return [];
-  if (answer.selections.length > 0) return answer.selections;
-  return answer.optionIndexes.map((optionIndex, index) => ({
-    optionIndex,
-    value: answer.values[index] ?? "",
-  }));
+): Selection[] {
+  if (!answer || answer.source !== "choice") return [];
+  return answer.selections;
 }
 
-export function renderNoteStatus(add: (text: string) => void, theme: Theme, note: string): void {
-  add("");
-  add(theme.fg("muted", ` Notes: ${note}`));
+export function renderNoteStatus(theme: Theme, note: string): string[] {
+  return ["", theme.fg("muted", ` Notes: ${note}`)];
 }

package/src/render/ui-rich-render-types.ts

@@ -0,0 +1,17 @@
+// Shared types used by the rich overlay rendering pipeline.
+// Extracted to avoid import cycles between render modules.
+
+export type SubMode = "select" | "other-input" | "text-input" | "discuss-input" | "note-input";
+
+export interface OverlayRenderState {
+  /** Current cursor row index within the interactive rows list. */
+  selectedIndex: number;
+  /** Active input mode: select, text-input, other-input, discuss-input, note-input. */
+  subMode: SubMode;
+  /** Uncommitted multi-select checkbox state (questionId → sorted optionIndexes). */
+  stagedSelections: Map<string, number[]>;
+  /** Draft note text for single-select questions (questionId → note). */
+  stagedSingleNotes: Map<string, string>;
+  /** Draft note text per-option for multi-select questions (questionId → Map<optionIndex, note>). */
+  stagedMultiNotes: Map<string, Map<number, string>>;
+}