@mrclrchtr/supi-ask-user 0.1.0 → 1.1.2

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

@@ -0,0 +1,323 @@
+// Pure rendering helpers for the rich overlay. Kept separate from
+// ui-rich.ts to stay within Biome's per-file line limit and so the input
+// dispatch logic can be read without scrolling past a wall of theme strings.
+
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { decorateOption, formatReviewLines, NOTE_MARKER } from "../format.ts";
+import type { NormalizedStructuredQuestion } from "../types.ts";
+import { inlineStructuredRowLines, structuredRowLabel } from "../ui/ui-rich-inline.ts";
+import {
+  hasPreview,
+  type InteractiveRow,
+  interactiveRows,
+  selectedIndexesForQuestion,
+} from "../ui/ui-rich-state.ts";
+import {
+  editorCaption,
+  padRight,
+  renderEditorBlock,
+  renderEditorPane,
+  usesSeparateEditorPane,
+} from "./ui-rich-render-editor.ts";
+import type { RenderEnv } from "./ui-rich-render-env.ts";
+import { footerHelp } from "./ui-rich-render-footer.ts";
+import { renderMarkdown, renderMarkdownPreview } from "./ui-rich-render-markdown.ts";
+import { currentNote, renderNoteStatus, visibleNoteMarker } from "./ui-rich-render-notes.ts";
+
+export function renderOverlay(env: RenderEnv): string[] {
+  const lines: string[] = [];
+  lines.push(env.theme.fg("accent", "─".repeat(env.width)));
+  if (env.flow.isMultiQuestion) renderTabBar(lines, env);
+  if (env.flow.currentMode === "reviewing") {
+    lines.push(...renderReview(env));
+  } else {
+    renderQuestion(lines, env);
+  }
+  lines.push(
+    truncateToWidth(env.theme.fg("dim", ` ${footerHelp(env.flow, env.state)}`), env.width),
+  );
+  lines.push(env.theme.fg("accent", "─".repeat(env.width)));
+  return lines;
+}
+
+function tabSegment(
+  env: RenderEnv,
+  text: string,
+  active: boolean,
+  color: "success" | "muted" | "dim" | "text",
+): string {
+  return active
+    ? env.theme.bg("selectedBg", env.theme.fg("text", text))
+    : env.theme.fg(color, text);
+}
+
+function renderTabBar(lines: string[], env: RenderEnv): void {
+  const segments: string[] = [env.theme.fg("dim", "← ")];
+  for (const [index, question] of env.flow.questions.entries()) {
+    const answered = env.flow.hasAnswer(question.id);
+    const active = env.flow.currentMode === "answering" && env.flow.currentIndex === index;
+    const marker = answered ? "■" : question.required ? "□" : "○";
+    const color = answered ? "success" : question.required ? "muted" : "dim";
+    segments.push(tabSegment(env, ` ${marker} ${question.header} `, active, color));
+    segments.push(" ");
+  }
+  const reviewActive = env.flow.currentMode === "reviewing";
+  segments.push(tabSegment(env, " ✓ Review ", reviewActive, reviewActive ? "text" : "dim"));
+  segments.push(env.theme.fg("dim", " →"));
+  lines.push(truncateToWidth(` ${segments.join("")}`, env.width));
+  lines.push("");
+}
+
+function renderQuestion(lines: string[], env: RenderEnv): void {
+  const question = env.flow.currentQuestion;
+  if (!question) return;
+  lines.push(...renderMarkdown(question.prompt, env.width - 1, env.theme, { paddingX: 0 }));
+  lines.push("");
+  if (question.type === "text") {
+    renderTextQuestion(lines, env);
+    return;
+  }
+  renderStructuredQuestion(lines, env, question);
+}
+
+function renderSplitView(
+  lines: string[],
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): void {
+  const leftWidth = Math.max(36, Math.floor(env.width * 0.55));
+  const rightWidth = Math.max(24, env.width - leftWidth - 3);
+  const leftEnv: RenderEnv = { ...env, width: leftWidth };
+  const leftLines = renderPaneRows(leftEnv, question, rows);
+  const rightLines = usesSeparateEditorPane(env.state)
+    ? renderEditorPane(rightWidth, env.theme, env.editor, editorCaption(env.state))
+    : renderPreviewPane(
+        rightWidth,
+        env.theme,
+        previewForSelection(question, rows[env.state.selectedIndex]),
+      );
+  const total = Math.max(leftLines.length, rightLines.length);
+  for (let index = 0; index < total; index += 1) {
+    const left = padRight(leftLines[index] ?? "", leftWidth);
+    const right = padRight(rightLines[index] ?? "", rightWidth);
+    lines.push(`${left} ${env.theme.fg("accent", "│")} ${right}`);
+  }
+}
+
+function renderTextQuestion(lines: string[], env: RenderEnv): void {
+  lines.push(...renderEditorBlock(env, "Answer"));
+}
+
+function renderStructuredQuestion(
+  lines: string[],
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+): void {
+  const rows = interactiveRows(question);
+  // Split view at >=100 cols: left pane 42% (min 34 cols) for option rows,
+  // right pane (min 24 cols) for preview or editor. Below this threshold,
+  // previews render as an inline block below the options.
+  if (hasPreview(question) && env.width >= 100) {
+    renderSplitView(lines, env, question, rows);
+  } else {
+    renderStandardStructuredQuestion(lines, env, question, rows);
+  }
+  const note = currentNote(env.flow, env.state, question);
+  if (note) lines.push(...renderNoteStatus(env.theme, note));
+}
+
+function renderStandardStructuredQuestion(
+  lines: string[],
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): void {
+  lines.push(...renderRows(env, question, rows));
+  if (usesSeparateEditorPane(env.state)) {
+    lines.push(...renderEditorBlock(env, editorCaption(env.state)));
+    return;
+  }
+  const preview = previewForSelection(question, rows[env.state.selectedIndex]);
+  if (preview) lines.push(...renderPreviewBlock(env, preview));
+}
+
+function renderPaneRows(
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): string[] {
+  return renderRows(env, question, rows);
+}
+
+/** Render a single interactive row, or its inline editor lines when the row
+ *  is an active other/discuss input and the editor is not rendered separately. */
+function renderInlineEditorLine(
+  env: RenderEnv,
+  prefix: string,
+  row: InteractiveRow,
+  out: string[],
+): boolean {
+  if (usesSeparateEditorPane(env.state)) return false;
+  const lines = inlineStructuredRowLines({
+    width: env.width,
+    theme: env.theme,
+    state: env.state,
+    editor: env.editor,
+    row,
+    prefix,
+  });
+  if (!lines) return false;
+  const continuation = " ".repeat(visibleWidth(prefix));
+  for (const [i, line] of lines.entries()) {
+    out.push(`${i === 0 ? prefix : continuation}${line}`);
+  }
+  return true;
+}
+
+function renderRows(
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+  rows: InteractiveRow[],
+): string[] {
+  const out: string[] = [];
+  for (const [index, row] of rows.entries()) {
+    const active = env.state.selectedIndex === index;
+    const prefix = active ? env.theme.fg("accent", "> ") : "  ";
+    if (renderInlineEditorLine(env, prefix, row, out)) continue;
+    addWrapped(out, env, prefix, rowLabel(env, question, row, active));
+    const description = rowDescription(question, row);
+    if (description) renderRowDescription(out, env, description);
+  }
+  return out;
+}
+
+function rowLabel(
+  env: RenderEnv,
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow,
+  active: boolean,
+): string {
+  const selected = selectedIndexesForQuestion(env.flow, env.state, question);
+  if (row.kind === "option") {
+    const option = question.options[row.optionIndex];
+    const recommended = question.recommendedIndexes.includes(row.optionIndex);
+    const noteMarker = visibleNoteMarker({
+      flow: env.flow,
+      state: env.state,
+      question,
+      row,
+      active,
+    });
+    const baseLabel = `${decorateOption(option.label, recommended)}${noteMarker ? ` ${NOTE_MARKER}` : ""}`;
+    if (question.multi) {
+      const checked = selected.includes(row.optionIndex) ? "[x]" : "[ ]";
+      return env.theme.fg("text", `${checked} ${baseLabel}`);
+    }
+    return env.theme.fg("text", `${row.optionIndex + 1}. ${baseLabel}`);
+  }
+  if (row.kind === "other")
+    return env.theme.fg("text", structuredRowLabel(env.flow, question, row));
+  return env.theme.fg("text", structuredRowLabel(env.flow, question, row));
+}
+
+function rowDescription(
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow,
+): string | undefined {
+  if (row.kind === "option") return question.options[row.optionIndex].description;
+  return undefined;
+}
+
+function renderRowDescription(out: string[], env: RenderEnv, description: string): void {
+  const descLines = renderMarkdown(description, env.width - 5, env.theme, {
+    paddingX: 0,
+    defaultColor: "muted",
+  });
+  for (const line of descLines) {
+    out.push(`     ${line}`);
+  }
+}
+
+function renderReviewAnswer(out: string[], env: RenderEnv, line: string): void {
+  const reviewLines = renderMarkdown(line, env.width - 3, env.theme, {
+    paddingX: 0,
+    defaultColor: "text",
+  });
+  for (const reviewLine of reviewLines) {
+    out.push(`   ${reviewLine}`);
+  }
+}
+
+function renderPreviewPane(
+  width: number,
+  theme: RenderEnv["theme"],
+  preview: string | undefined,
+): string[] {
+  const out: string[] = [];
+  const push = (text = "") => out.push(text);
+  push(theme.fg("accent", " Preview"));
+  push("");
+  if (!preview) {
+    push(theme.fg("muted", " No preview for the current selection."));
+    return out;
+  }
+  out.push(...renderMarkdownPreview(preview, width, theme));
+  return out;
+}
+
+function renderPreviewBlock(env: RenderEnv, preview: string): string[] {
+  const out: string[] = [];
+  out.push("");
+  out.push(env.theme.fg("accent", " Preview:"));
+  out.push(...renderMarkdownPreview(preview, env.width, env.theme));
+  return out;
+}
+
+function previewForSelection(
+  question: NormalizedStructuredQuestion,
+  row: InteractiveRow | undefined,
+): string | undefined {
+  return row?.kind === "option" ? question.options[row.optionIndex].preview : undefined;
+}
+
+function renderReview(env: RenderEnv): string[] {
+  const out: string[] = [];
+  const add = (text: string) => out.push(truncateToWidth(text, env.width));
+  add(env.theme.fg("accent", " Review answers:"));
+  add("");
+  for (const question of env.flow.questions) {
+    const answer = env.flow.getAnswer(question.id);
+    const answerLines = answer
+      ? formatReviewLines(question, answer)
+      : [question.required ? "(no answer)" : "(skipped)"];
+    add(env.theme.fg("muted", ` ${question.header}:`));
+    for (const line of answerLines) renderReviewAnswer(out, env, line);
+  }
+  add("");
+  if (env.flow.showSkip) {
+    add(
+      env.theme.fg(
+        env.flow.allRequiredAnswered() ? "success" : "warning",
+        " Press Enter to submit • s to skip",
+      ),
+    );
+  } else {
+    add(
+      env.theme.fg(
+        env.flow.allRequiredAnswered() ? "success" : "warning",
+        " Press Enter to submit",
+      ),
+    );
+  }
+  return out;
+}
+
+function addWrapped(lines: string[], env: RenderEnv, prefix: string, text: string): void {
+  const prefixWidth = visibleWidth(prefix);
+  const contentWidth = Math.max(1, env.width - prefixWidth);
+  const continuationPrefix = " ".repeat(prefixWidth);
+  for (const [index, line] of wrapTextWithAnsi(text, contentWidth).entries()) {
+    lines.push(`${index === 0 ? prefix : continuationPrefix}${line}`);
+  }
+}

package/{render.ts → src/render.ts}

@@ -2,21 +2,19 @@
 // session transcript readable: a one-line "asking N questions: …" header on
 // the call, and a compact ✓ / cancelled / aborted summary on the result.
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { Text, truncateToWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { formatSummaryBody } from "./format.ts";
 import { ASK_USER_ERROR_MARKER } from "./result.ts";
 import type { AskUserDetails, NormalizedQuestion } from "./types.ts";
 
-const MAX_HEADER_LIST = 60;
-
 export function renderAskUserCall(args: unknown, theme: Theme): Text {
   const headers = extractHeadersFromArgs(args);
   const count = headers.length;
   let text = theme.fg("toolTitle", theme.bold("ask_user "));
   text += theme.fg("muted", `${count || "?"} question${count === 1 ? "" : "s"}`);
   if (count > 0) {
-    text += theme.fg("dim", ` (${truncateToWidth(headers.join(", "), MAX_HEADER_LIST)})`);
+    text += theme.fg("dim", ` (${headers.join(", ")})`);
   }
   return new Text(text, 0, 0);
 }
@@ -33,6 +31,13 @@ export function renderAskUserResult(
     const fallback = result.content[0];
     return new Text(fallback?.type === "text" ? (fallback.text ?? "") : "", 0, 0);
   }
+  if (details.terminalState === "skipped") {
+    return new Text(
+      `${theme.fg("dim", "Skipped")}\n${formatSubmittedSummary(details, theme)}`,
+      0,
+      0,
+    );
+  }
   if (details.terminalState === "cancelled") {
     return new Text(theme.fg("warning", "Cancelled"), 0, 0);
   }

package/{result.ts → src/result.ts}

@@ -14,25 +14,32 @@ import type {
 export interface HybridResult {
   content: { type: "text"; text: string }[];
   details: AskUserDetails;
+  skip?: true;
 }
 
 export function buildResult(
   questions: NormalizedQuestion[],
   outcome: QuestionnaireOutcome,
 ): HybridResult {
-  return {
+  const result: HybridResult = {
     content: [{ type: "text", text: summarize(questions, outcome) }],
     details: {
       questions,
       answers: outcome.answers,
-      answersById: indexById(outcome.answers),
+      answersById: indexById(questions, outcome.answers),
       terminalState: outcome.terminalState,
     },
   };
+  if (outcome.skipped) result.skip = true;
+  return result;
 }
 
-function indexById(answers: Answer[]): Record<string, Answer> {
-  const out: Record<string, Answer> = {};
+function indexById(
+  questions: NormalizedQuestion[],
+  answers: Answer[],
+): Record<string, Answer | undefined> {
+  const out: Record<string, Answer | undefined> = {};
+  for (const question of questions) out[question.id] = undefined;
   for (const answer of answers) out[answer.questionId] = answer;
   return out;
 }
@@ -53,6 +60,13 @@ export function buildErrorResult(message: string): HybridResult {
 }
 
 function summarize(questions: NormalizedQuestion[], outcome: QuestionnaireOutcome): string {
+  if (outcome.terminalState === "skipped") {
+    const byId = new Map(outcome.answers.map((answer) => [answer.questionId, answer]));
+    const lines = questions.map((question) =>
+      formatAnswerLine(question, byId.get(question.id), true),
+    );
+    return `User skipped the questionnaire.\n${lines.join("\n")}`;
+  }
   if (outcome.terminalState !== "submitted") return summarizeTerminal(outcome.terminalState);
   const byId = new Map(outcome.answers.map((answer) => [answer.questionId, answer]));
   return questions.map((question) => formatAnswerLine(question, byId.get(question.id))).join("\n");
@@ -63,7 +77,14 @@ function summarizeTerminal(state: TerminalState): string {
   return "Questionnaire was aborted before the user submitted answers.";
 }
 
-function formatAnswerLine(question: NormalizedQuestion, answer: Answer | undefined): string {
-  if (!answer) return `${question.header}: (no answer)`;
+function formatAnswerLine(
+  question: NormalizedQuestion,
+  answer: Answer | undefined,
+  skipped = false,
+): string {
+  if (!answer) {
+    if (skipped && !question.required) return `${question.header}: (skipped)`;
+    return `${question.header}: (no answer)`;
+  }
   return `${question.header}: ${formatSummaryBody(question, answer)}`;
 }

package/{schema.ts → src/schema.ts}

@@ -1,14 +1,19 @@
 // External (model-facing) parameter schema for the `ask_user` tool.
-// Rich-TUI-first redesign: explicit question kinds, explicit escape hatches,
-// and first-class option previews for structured comparisons.
+// Two question types: choice (structured pick-one-or-many with options)
+// and text (freeform input). Yes/no and multichoice have been unified
+// into choice — yes/no is just choice with two options, multi-select
+// is choice with `multi: true`.
 
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 
 const StructuredOptionSchema = Type.Object({
   value: Type.String({ description: "Stable identifier returned in the answer" }),
   label: Type.String({ description: "Display label shown to the user" }),
   description: Type.Optional(
-    Type.String({ description: "Optional one-line clarification shown under the label" }),
+    Type.String({
+      description:
+        "Optional clarification shown under the label (wraps naturally, a short paragraph is fine)",
+    }),
   ),
   preview: Type.Optional(
     Type.String({
@@ -18,13 +23,20 @@ const StructuredOptionSchema = Type.Object({
   ),
 });
 
-const StructuredQuestionBaseSchema = {
+const ChoiceQuestionSchema = Type.Object({
+  type: Type.Literal("choice"),
   id: Type.String({ description: "Unique question id within this questionnaire" }),
   header: Type.String({ description: "Short label (chip) describing the decision" }),
   prompt: Type.String({ description: "Full question text shown to the user" }),
   options: Type.Array(StructuredOptionSchema, {
-    description: "Allowed answers (2-8). Use distinct, mutually exclusive options.",
+    description: "Allowed answers (2-12). Use distinct, mutually exclusive options.",
   }),
+  required: Type.Optional(
+    Type.Boolean({
+      default: true,
+      description: "Whether this question must be answered before submission (default true)",
+    }),
+  ),
   allowOther: Type.Optional(
     Type.Boolean({
       description: "Allow an explicit custom answer path instead of forcing one of the options",
@@ -36,23 +48,23 @@ const StructuredQuestionBaseSchema = {
         "Allow the user to choose discussion instead of committing to a decision right now",
     }),
   ),
-} as const;
-
-const ChoiceQuestionSchema = Type.Object({
-  type: Type.Literal("choice"),
-  ...StructuredQuestionBaseSchema,
-  recommendation: Type.Optional(
-    Type.String({ description: "Recommended option `value` (must match one of `options`)" }),
+  multi: Type.Optional(
+    Type.Boolean({
+      default: false,
+      description:
+        "Allow selecting multiple options (multi-select). Default false (single-select).",
+    }),
   ),
-});
-
-const MultiChoiceQuestionSchema = Type.Object({
-  type: Type.Literal("multichoice"),
-  ...StructuredQuestionBaseSchema,
   recommendation: Type.Optional(
-    Type.Array(Type.String(), {
+    Type.Union([Type.String(), Type.Array(Type.String())], {
       description:
-        "Recommended option `value`s for multi-select questions (each must match one of `options`)",
+        "Recommended option value(s). String for single-select, array for multi-select. Each must match an option value.",
+    }),
+  ),
+  default: Type.Optional(
+    Type.Union([Type.String(), Type.Array(Type.String())], {
+      description:
+        "Pre-selected option value(s). String for single-select, array for multi-select. Each must match an option value.",
     }),
   ),
 });
@@ -62,42 +74,32 @@ const TextQuestionSchema = Type.Object({
   id: Type.String({ description: "Unique question id within this questionnaire" }),
   header: Type.String({ description: "Short label (chip) describing the prompt" }),
   prompt: Type.String({ description: "Full question text shown to the user" }),
-});
-
-const YesNoQuestionSchema = Type.Object({
-  type: Type.Literal("yesno"),
-  id: Type.String({ description: "Unique question id within this questionnaire" }),
-  header: Type.String({ description: "Short label (chip) describing the decision" }),
-  prompt: Type.String({ description: "Full yes/no question shown to the user" }),
-  allowOther: Type.Optional(
-    Type.Boolean({ description: "Allow an explicit custom answer path besides yes/no" }),
-  ),
-  allowDiscuss: Type.Optional(
-    Type.Boolean({ description: "Allow discussion instead of choosing yes or no" }),
-  ),
-  recommendation: Type.Optional(
-    Type.Union([Type.Literal("yes"), Type.Literal("no")], {
-      description: "Recommended answer (`yes` or `no`)",
+  required: Type.Optional(
+    Type.Boolean({
+      default: true,
+      description: "Whether this question must be answered before submission (default true)",
     }),
   ),
+  default: Type.Optional(
+    Type.String({ description: "Pre-filled default value shown in the text input" }),
+  ),
 });
 
-const QuestionSchema = Type.Union([
-  ChoiceQuestionSchema,
-  MultiChoiceQuestionSchema,
-  TextQuestionSchema,
-  YesNoQuestionSchema,
-]);
+const QuestionSchema = Type.Union([ChoiceQuestionSchema, TextQuestionSchema]);
 
 export const AskUserParamsSchema = Type.Object({
   questions: Type.Array(QuestionSchema, {
     description: "Between 1 and 4 focused decision questions",
   }),
+  allowSkip: Type.Optional(
+    Type.Boolean({
+      description:
+        "Expose a Skip action so the user can submit a partial result without answering all questions",
+    }),
+  ),
 });
 
 export type AskUserParams = Static<typeof AskUserParamsSchema>;
 export type ExternalQuestion = Static<typeof QuestionSchema>;
 export type ExternalChoiceQuestion = Static<typeof ChoiceQuestionSchema>;
-export type ExternalMultiChoiceQuestion = Static<typeof MultiChoiceQuestionSchema>;
 export type ExternalTextQuestion = Static<typeof TextQuestionSchema>;
-export type ExternalYesNoQuestion = Static<typeof YesNoQuestionSchema>;