@mrclrchtr/supi-ask-user 1.3.1 → 1.5.0

package/src/ui/overlay-view.ts

@@ -0,0 +1,313 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { SelectItem } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { AskUserController } from "../session/controller.ts";
+import type { NormalizedChoiceQuestion } from "../types.ts";
+
+export type OverlayAction = "other" | "skip" | "discuss" | "partial";
+export type FocusTarget = "choices" | "editor" | "actions";
+export type OverlayMode = "choice" | "text" | "custom-input" | "discuss-input" | "note-input";
+
+export type ChoiceRow =
+  | { kind: "option"; optionIndex: number }
+  | { kind: "action"; action: OverlayAction };
+
+export function buildChoiceRows(
+  controller: AskUserController,
+  question: NormalizedChoiceQuestion,
+): ChoiceRow[] {
+  const rows: ChoiceRow[] = question.options.map((_option, optionIndex) => ({
+    kind: "option",
+    optionIndex,
+  }));
+  if (question.allowOther) rows.push({ kind: "action", action: "other" });
+  rows.push(
+    ...buildExceptionalActions(controller, question.required).map((action) => ({
+      kind: "action" as const,
+      action,
+    })),
+  );
+  return rows;
+}
+
+export function buildChoiceItems(
+  controller: AskUserController,
+  question: NormalizedChoiceQuestion,
+  rows: ChoiceRow[],
+): SelectItem[] {
+  const selectedIndexes = new Set(controller.getSelectedIndexes(question));
+  return rows.flatMap((row) => {
+    if (row.kind === "option") {
+      const option = question.options[row.optionIndex];
+      return option
+        ? [
+            buildOptionItem({
+              question,
+              optionIndex: row.optionIndex,
+              label: option.label,
+              selectedIndexes,
+              hasNote: !!controller.getChoiceOptionNote(question.id, option.value),
+            }),
+          ]
+        : [];
+    }
+    return [buildActionItem(controller, question.id, row.action)];
+  });
+}
+
+export function buildTextActionItems(
+  controller: AskUserController,
+): Array<{ action: OverlayAction; item: SelectItem }> {
+  return buildExceptionalActions(controller, controller.currentQuestion.required).map((action) => ({
+    action,
+    item: {
+      value: action,
+      label: actionLabel(action),
+    },
+  }));
+}
+
+export function defaultChoiceRowIndex(
+  controller: AskUserController,
+  question: NormalizedChoiceQuestion,
+  rows: ChoiceRow[],
+): number {
+  const current = controller.getAnswer(question.id);
+  if (current?.kind === "custom") {
+    return rows.findIndex((row) => row.kind === "action" && row.action === "other");
+  }
+  if (current?.kind === "choice") {
+    const first = current.selections[0];
+    if (!first) return 0;
+    const optionIndex = question.options.findIndex((option) => option.value === first.value);
+    return optionIndex >= 0 ? optionIndex : 0;
+  }
+  return question.initialIndexes[0] ?? question.recommendedIndexes[0] ?? 0;
+}
+
+export function previewOptionIndexForRows(
+  rows: ChoiceRow[],
+  rowIndex: number,
+  fallbackOptionIndex: number,
+): number | undefined {
+  const row = rows[rowIndex];
+  if (row?.kind === "option") return row.optionIndex;
+  return fallbackOptionIndex >= 0 ? fallbackOptionIndex : undefined;
+}
+
+export function footerText(args: {
+  controller: AskUserController;
+  mode: OverlayMode;
+  focus: FocusTarget;
+  hasTextActions: boolean;
+}): string {
+  const { controller, mode, focus, hasTextActions } = args;
+  const question = controller.currentQuestion;
+
+  if (question.type === "text") {
+    if (mode === "discuss-input") return "Enter submit • Esc cancel";
+    if (focus === "editor") {
+      return hasTextActions
+        ? "Enter submit • ↓ actions • ← back • Esc cancel"
+        : "Enter submit • ← back • Esc cancel";
+    }
+    return "↑↓ move • Enter select • ↑ editor • ← back • Esc cancel";
+  }
+
+  if (mode === "custom-input" || mode === "discuss-input") {
+    return "Enter submit • Esc cancel";
+  }
+  if (mode === "note-input") {
+    return "Enter save • Esc close";
+  }
+  return question.multi
+    ? "↑↓ move • Space toggle • Enter submit • n note • ← back • Esc cancel"
+    : "↑↓ move • Space select • Enter submit • n note • ← back • Esc cancel";
+}
+
+export function splitColumns(args: {
+  width: number;
+  theme: Theme;
+  leftLines: string[];
+  rightLines: string[];
+  leftRatio?: number;
+}): string[] {
+  const { width, theme, leftLines, rightLines, leftRatio = 0.55 } = args;
+  const leftWidth = Math.max(36, Math.floor(width * leftRatio));
+  const rightWidth = Math.max(24, width - leftWidth - 3);
+  const total = Math.max(leftLines.length, rightLines.length);
+  const lines: string[] = [];
+
+  for (let index = 0; index < total; index += 1) {
+    const left = padRight(leftLines[index] ?? "", leftWidth);
+    const right = padRight(rightLines[index] ?? "", rightWidth);
+    lines.push(`${left} ${theme.fg("accent", "│")} ${right}`);
+  }
+  return lines;
+}
+
+export function choiceRowValue(row: ChoiceRow): string {
+  return row.kind === "option" ? `option:${row.optionIndex}` : `action:${row.action}`;
+}
+
+function renderOptionRow(args: {
+  option: { label: string; description?: string };
+  labelText: string;
+  isSelected: boolean;
+  theme: Theme;
+  width: number;
+}): string[] {
+  const { theme, isSelected, labelText, width, option } = args;
+  const prefix = isSelected ? "\u2192 " : "  ";
+
+  const lines: string[] = [
+    isSelected ? theme.fg("accent", `${prefix}${labelText}`) : `${prefix}${labelText}`,
+  ];
+
+  if (option.description) {
+    const descWidth = Math.max(10, width - 2);
+    const wrapped = wrapTextWithAnsi(option.description, descWidth);
+    for (const descLine of wrapped) {
+      lines.push(theme.fg("muted", `  ${descLine}`));
+    }
+  }
+
+  return lines;
+}
+
+function renderActionRow(args: {
+  actionLabel: string;
+  isSelected: boolean;
+  theme: Theme;
+}): string[] {
+  const { theme, isSelected, actionLabel } = args;
+  const prefix = isSelected ? "\u2192 " : "  ";
+  return [isSelected ? theme.fg("accent", `${prefix}${actionLabel}`) : `${prefix}${actionLabel}`];
+}
+
+function prepareOptionMarker(
+  question: NormalizedChoiceQuestion,
+  optionIndex: number,
+  selectedIndexes: Set<number>,
+): string {
+  if (question.multi) {
+    return selectedIndexes.has(optionIndex) ? "[x]" : "[ ]";
+  }
+  return selectedIndexes.has(optionIndex) ? "(*)" : "( )";
+}
+
+function prepareOptionLabel(
+  option: { label: string },
+  marker: string,
+  recommended: boolean,
+  hasNote: boolean,
+): string {
+  return `${marker} ${option.label}${recommended ? " (recommended)" : ""}${hasNote ? " [note]" : ""}`;
+}
+
+export function renderChoiceList(args: {
+  controller: AskUserController;
+  question: NormalizedChoiceQuestion;
+  rows: ChoiceRow[];
+  selectedIndex: number;
+  theme: Theme;
+  width: number;
+}): string[] {
+  const { controller, question, rows, selectedIndex, theme, width } = args;
+  const lines: string[] = [];
+  const selectedIndexes = new Set(controller.getSelectedIndexes(question));
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    const isSelected = i === selectedIndex;
+
+    if (row.kind === "option") {
+      const option = question.options[row.optionIndex];
+      if (!option) continue;
+
+      const marker = prepareOptionMarker(question, row.optionIndex, selectedIndexes);
+      const recommended = question.recommendedIndexes.includes(row.optionIndex);
+      const hasNote = !!controller.getChoiceOptionNote(question.id, option.value);
+      const labelText = prepareOptionLabel(option, marker, recommended, hasNote);
+
+      lines.push(...renderOptionRow({ option, labelText, isSelected, theme, width }));
+    } else {
+      const answer = controller.getAnswer(question.id);
+      const actionLabelText =
+        row.action === "other" && answer?.kind === "custom"
+          ? `Other \u2014 ${answer.value}`
+          : actionLabel(row.action);
+
+      lines.push(...renderActionRow({ actionLabel: actionLabelText, isSelected, theme }));
+    }
+  }
+
+  return lines;
+}
+
+function buildOptionItem(args: {
+  question: NormalizedChoiceQuestion;
+  optionIndex: number;
+  label: string;
+  selectedIndexes: Set<number>;
+  hasNote: boolean;
+}): SelectItem {
+  const { question, optionIndex, label, selectedIndexes, hasNote } = args;
+  const recommended = question.recommendedIndexes.includes(optionIndex) ? " (recommended)" : "";
+  const marker = question.multi
+    ? selectedIndexes.has(optionIndex)
+      ? "[x]"
+      : "[ ]"
+    : selectedIndexes.has(optionIndex)
+      ? "(*)"
+      : "( )";
+  return {
+    value: choiceRowValue({ kind: "option", optionIndex }),
+    label: `${marker} ${label}${recommended}${hasNote ? " [note]" : ""}`,
+  };
+}
+
+function buildActionItem(
+  controller: AskUserController,
+  questionId: string,
+  action: OverlayAction,
+): SelectItem {
+  const answer = controller.getAnswer(questionId);
+  return {
+    value: choiceRowValue({ kind: "action", action }),
+    label:
+      action === "other" && answer?.kind === "custom"
+        ? `Other — ${answer.value}`
+        : actionLabel(action),
+  };
+}
+
+function buildExceptionalActions(
+  controller: AskUserController,
+  required: boolean,
+): OverlayAction[] {
+  const actions: OverlayAction[] = [];
+  if (!required) actions.push("skip");
+  if (controller.questionnaire.allowDiscuss) actions.push("discuss");
+  if (controller.canPartialSubmit()) actions.push("partial");
+  return actions;
+}
+
+function actionLabel(action: OverlayAction): string {
+  switch (action) {
+    case "other":
+      return "Other…";
+    case "skip":
+      return "Skip question";
+    case "discuss":
+      return "Discuss instead…";
+    case "partial":
+      return "Submit partial answers";
+  }
+}
+
+function padRight(text: string, width: number): string {
+  const visible = visibleWidth(text);
+  if (visible >= width) return truncateToWidth(text, width);
+  return `${text}${" ".repeat(width - visible)}`;
+}

package/src/ui/overlay.ts

@@ -0,0 +1,28 @@
+import { AskUserController } from "../session/controller.ts";
+import type { AskUserOutcome, NormalizedQuestionnaire } from "../types.ts";
+import { AskUserOverlay } from "./overlay-component.ts";
+import type { RunQuestionnaireOptions } from "./types.ts";
+
+export async function runOverlayQuestionnaire(
+  questionnaire: NormalizedQuestionnaire,
+  opts: RunQuestionnaireOptions,
+): Promise<AskUserOutcome> {
+  const controller = new AskUserController(questionnaire);
+  if (opts.signal?.aborted) {
+    controller.abort();
+    return controller.outcome();
+  }
+
+  return opts.ui.custom?.<AskUserOutcome>(
+    (tui, theme, kb, done) =>
+      new AskUserOverlay({
+        tui,
+        theme,
+        controller,
+        done,
+        signal: opts.signal,
+        keybindings: kb,
+        onToggleToolsExpanded: opts.onToggleToolsExpanded,
+      }),
+  ) as Promise<AskUserOutcome>;
+}

package/src/ui/types.ts

@@ -0,0 +1,38 @@
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { AskUserController } from "../session/controller.ts";
+import type { AskUserOutcome, NormalizedQuestionnaire } from "../types.ts";
+
+export interface AskUserUiContext {
+  notify?(message: string, type?: "info" | "warning" | "error"): void;
+  custom?<T>(
+    factory: (
+      tui: TUI,
+      theme: Theme,
+      keybindings: KeybindingsManager,
+      done: (result: T) => void,
+    ) => Component & { dispose?(): void },
+  ): Promise<T>;
+}
+
+export interface RunQuestionnaireOptions {
+  ui: AskUserUiContext;
+  signal?: AbortSignal;
+  /** Callback to toggle tool output expansion (Ctrl+O passthrough). */
+  onToggleToolsExpanded?: () => void;
+}
+
+export interface RenderContext {
+  questionnaire: NormalizedQuestionnaire;
+  options: RunQuestionnaireOptions;
+}
+
+export interface OverlayArgs {
+  tui: TUI;
+  theme: Theme;
+  controller: AskUserController;
+  done: (result: AskUserOutcome) => void;
+  signal?: AbortSignal;
+  keybindings: KeybindingsManager;
+  onToggleToolsExpanded?: () => void;
+}

package/src/flow.ts

@@ -1,224 +0,0 @@
-// Shared questionnaire flow state used by the overlay UI and the
-// single-active-questionnaire concurrency guard. The flow owns terminal-state
-// transitions (`submitted`, `cancelled`, `aborted`) to keep cancellation/abort
-// semantics consistent.
-
-import type { Answer, NormalizedQuestion, QuestionnaireOutcome, TerminalState } from "./types.ts";
-import { needsReview } from "./types.ts";
-
-export type FlowMode = "answering" | "reviewing" | "terminal";
-
-export class QuestionnaireFlow {
-  private readonly answers = new Map<string, Answer>();
-  private index = 0;
-  private mode: FlowMode = "answering";
-  private terminalState: TerminalState | null = null;
-
-  constructor(
-    public readonly questions: NormalizedQuestion[],
-    public readonly allowSkip = false,
-  ) {
-    if (questions.length === 0) {
-      throw new Error("QuestionnaireFlow requires at least one question.");
-    }
-  }
-
-  get hasOptionalQuestions(): boolean {
-    return this.questions.some((q) => !q.required);
-  }
-
-  get showSkip(): boolean {
-    return this.allowSkip || this.hasOptionalQuestions;
-  }
-
-  get currentIndex(): number {
-    return this.index;
-  }
-
-  get currentMode(): FlowMode {
-    return this.mode;
-  }
-
-  get isMultiQuestion(): boolean {
-    return this.questions.length > 1;
-  }
-
-  get currentQuestion(): NormalizedQuestion | undefined {
-    return this.questions[this.index];
-  }
-
-  hasAnswer(questionId: string): boolean {
-    return this.answers.has(questionId);
-  }
-
-  getAnswer(questionId: string): Answer | undefined {
-    return this.answers.get(questionId);
-  }
-
-  allAnswered(): boolean {
-    return this.questions.every((q) => this.answers.has(q.id));
-  }
-
-  allRequiredAnswered(): boolean {
-    return this.questions.every((q) => !q.required || this.answers.has(q.id));
-  }
-
-  setAnswer(answer: Answer): void {
-    this.answers.set(answer.questionId, normalizeAnswer(answer));
-  }
-
-  advance(): boolean {
-    if (this.mode !== "answering") return false;
-    const current = this.currentQuestion;
-    if (current?.required && !this.answers.has(current.id)) return false;
-    if (this.index < this.questions.length - 1) {
-      this.index += 1;
-      return true;
-    }
-    if (needsReview(this.questions)) {
-      this.mode = "reviewing";
-      return true;
-    }
-    this.markSubmitted();
-    return true;
-  }
-
-  goBack(): boolean {
-    if (!this.guardNotTerminal()) return false;
-    if (this.mode === "reviewing") {
-      this.mode = "answering";
-      this.index = this.questions.length - 1;
-      return true;
-    }
-    if (this.index > 0) {
-      this.index -= 1;
-      return true;
-    }
-    return false;
-  }
-
-  enterReview(): boolean {
-    if (!this.guardNotTerminal()) return false;
-    if (!needsReview(this.questions)) return false;
-    if (!this.allRequiredAnswered()) return false;
-    this.mode = "reviewing";
-    return true;
-  }
-
-  submit(): boolean {
-    if (!this.guardNotTerminal()) return false;
-    if (!this.allRequiredAnswered()) return false;
-    this.markSubmitted();
-    return true;
-  }
-
-  skip(): boolean {
-    if (!this.guardNotTerminal()) return false;
-    this.mode = "terminal";
-    this.terminalState = "skipped";
-    return true;
-  }
-
-  cancel(): void {
-    if (!this.guardNotTerminal()) return;
-    this.mode = "terminal";
-    this.terminalState = "cancelled";
-  }
-
-  abort(): void {
-    if (!this.guardNotTerminal()) return;
-    this.mode = "terminal";
-    this.terminalState = "aborted";
-  }
-
-  isTerminal(): boolean {
-    return this.mode === "terminal";
-  }
-
-  outcome(): QuestionnaireOutcome {
-    const state = this.terminalState ?? "cancelled";
-    return {
-      terminalState: state,
-      answers:
-        state === "submitted" || state === "skipped"
-          ? this.collectAnswers()
-          : [...this.answers.values()],
-      ...(state === "skipped" ? { skipped: true } : {}),
-    };
-  }
-
-  private guardNotTerminal(): boolean {
-    return this.mode !== "terminal";
-  }
-
-  private markSubmitted(): void {
-    this.mode = "terminal";
-    this.terminalState = "submitted";
-  }
-
-  private collectAnswers(): Answer[] {
-    return this.questions.flatMap((q) => {
-      const answer = this.answers.get(q.id);
-      return answer ? [answer] : [];
-    });
-  }
-}
-
-function normalizeAnswer(answer: Answer): Answer {
-  switch (answer.source) {
-    case "choice":
-      return {
-        questionId: answer.questionId,
-        source: "choice",
-        selections: answer.selections.map((selection) => ({
-          value: selection.value.trim(),
-          optionIndex: selection.optionIndex,
-          note: trimOptional(selection.note),
-        })),
-      };
-    case "other":
-      return {
-        questionId: answer.questionId,
-        source: "other",
-        value: answer.value.trim(),
-      };
-    case "discuss": {
-      const value = trimOptional(answer.value);
-      return value
-        ? { questionId: answer.questionId, source: "discuss", value }
-        : { questionId: answer.questionId, source: "discuss" };
-    }
-    case "text":
-      return {
-        questionId: answer.questionId,
-        source: "text",
-        value: answer.value.trim(),
-      };
-  }
-}
-
-function trimOptional(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : undefined;
-}
-
-// Session-scoped lock: only one in-flight `ask_user` interaction at a time.
-// Stored at module scope per extension instance (the extension factory runs
-// once per session in pi).
-export class ActiveQuestionnaireLock {
-  private active = false;
-
-  acquire(): boolean {
-    if (this.active) return false;
-    this.active = true;
-    return true;
-  }
-
-  release(): void {
-    this.active = false;
-  }
-
-  isActive(): boolean {
-    return this.active;
-  }
-}

package/src/format.ts

@@ -1,66 +0,0 @@
-// 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;
-}