@mrclrchtr/supi-ask-user 1.3.1 → 1.4.0

package/src/ui/overlay.ts

@@ -0,0 +1,388 @@
+import {
+  type Component,
+  Editor,
+  type Focusable,
+  Key,
+  matchesKey,
+  SelectList,
+} from "@earendil-works/pi-tui";
+import { AskUserController } from "../session/controller.ts";
+import type {
+  AskUserOutcome,
+  NormalizedChoiceQuestion,
+  NormalizedQuestionnaire,
+} from "../types.ts";
+import { createActionList } from "./overlay-actions.ts";
+import {
+  clampIndex,
+  currentCustomValue,
+  currentPreviewText,
+  currentTextValue,
+  makeEditorTheme,
+  makeSelectListTheme,
+  renderOverlayFrame,
+} from "./overlay-render.ts";
+import {
+  buildChoiceItems,
+  buildChoiceRows,
+  type ChoiceRow,
+  choiceRowValue,
+  defaultChoiceRowIndex,
+  type FocusTarget,
+  type OverlayAction,
+  type OverlayMode,
+  previewOptionIndexForRows,
+} from "./overlay-view.ts";
+import type { OverlayArgs, 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 }),
+  ) as Promise<AskUserOutcome>;
+}
+
+class AskUserOverlay implements Component, Focusable {
+  focused = false;
+
+  private readonly editor: Editor;
+  private focus: FocusTarget = "choices";
+  private mode: OverlayMode = "choice";
+  private closed = false;
+  private cachedWidth: number | undefined;
+  private cachedLines: string[] | undefined;
+  private readonly onAbort: () => void;
+
+  private choiceRows: ChoiceRow[] = [];
+  private choiceRowIndex = 0;
+  private previewOptionIndex = 0;
+  private choiceList: SelectList | undefined;
+
+  private textActions: Array<{ action: OverlayAction; label: string }> = [];
+  private actionIndex = 0;
+  private actionList: SelectList | undefined;
+
+  constructor(private readonly args: OverlayArgs) {
+    this.editor = new Editor(args.tui, makeEditorTheme(args.theme));
+    this.editor.onSubmit = (value) => this.handleEditorSubmit(value);
+    this.syncCurrentQuestion();
+    this.onAbort = () => {
+      this.args.controller.abort();
+      this.finish();
+    };
+    args.signal?.addEventListener("abort", this.onAbort);
+  }
+
+  render(width: number): string[] {
+    this.editor.focused = this.focus === "editor";
+    if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+
+    this.cachedWidth = width;
+    this.cachedLines = renderOverlayFrame({
+      width,
+      theme: this.args.theme,
+      controller: this.args.controller,
+      mode: this.mode,
+      focus: this.focus,
+      editor: this.editor,
+      choiceList: this.choiceList,
+      actionList: this.actionList,
+      textActionLabels: this.textActions.map(({ label }) => label),
+      previewText: currentPreviewText(
+        this.args.controller.currentQuestion,
+        this.previewOptionIndex,
+      ),
+    });
+    return this.cachedLines;
+  }
+
+  handleInput(data: string): void {
+    if (this.closed || this.args.controller.isTerminal) return;
+
+    if (matchesKey(data, Key.escape)) {
+      this.args.controller.cancel();
+      this.finish();
+      return;
+    }
+    if (matchesKey(data, Key.left)) {
+      if (this.args.controller.goBack()) {
+        this.syncCurrentQuestion();
+        this.refresh();
+      }
+      return;
+    }
+
+    switch (this.focus) {
+      case "choices":
+        this.handleChoiceKey(data);
+        return;
+      case "actions":
+        this.handleActionKey(data);
+        return;
+      case "editor":
+        this.handleEditorKey(data);
+        return;
+    }
+  }
+
+  invalidate(): void {
+    this.cachedLines = undefined;
+    this.choiceList?.invalidate();
+    this.actionList?.invalidate();
+    this.editor.invalidate();
+  }
+
+  dispose(): void {
+    this.closed = true;
+    this.args.signal?.removeEventListener("abort", this.onAbort);
+  }
+
+  private handleChoiceKey(data: string): void {
+    const question = this.args.controller.currentQuestion;
+    if (question.type !== "choice" || !this.choiceList) return;
+
+    if (matchesKey(data, Key.space)) {
+      const row = this.choiceRows[this.choiceRowIndex];
+      if (row?.kind === "option") this.applyChoiceSelection(question, row.optionIndex, false);
+      return;
+    }
+
+    this.choiceList.handleInput(data);
+    this.refresh();
+  }
+
+  private handleActionKey(data: string): void {
+    const question = this.args.controller.currentQuestion;
+    if (!this.actionList) return;
+
+    if (question.type === "text") {
+      if (matchesKey(data, Key.up) && this.actionIndex === 0) {
+        this.focus = "editor";
+        this.refresh();
+        return;
+      }
+    } else if (matchesKey(data, Key.up) && this.actionIndex === 0) {
+      this.focus = "choices";
+      this.refresh();
+      return;
+    }
+
+    this.actionList.handleInput(data);
+    this.refresh();
+  }
+
+  private handleEditorKey(data: string): void {
+    if (this.mode === "text" && matchesKey(data, Key.down) && this.textActions.length > 0) {
+      this.focus = "actions";
+      this.refresh();
+      return;
+    }
+
+    this.editor.handleInput(data);
+    this.refresh();
+  }
+
+  private handleEditorSubmit(value: string): void {
+    const trimmed = value.trim();
+    const question = this.args.controller.currentQuestion;
+
+    if (this.mode === "discuss-input") {
+      this.args.controller.finishDiscuss(trimmed || undefined);
+      this.finish();
+      return;
+    }
+    if (this.mode === "custom-input") {
+      if (trimmed.length === 0) return;
+      this.args.controller.setAnswer(question.id, { kind: "custom", value: trimmed });
+      this.advanceAfterQuestion();
+      return;
+    }
+    if (trimmed.length === 0) {
+      if (question.required) return;
+      this.args.controller.clearAnswer(question.id);
+      this.advanceAfterQuestion();
+      return;
+    }
+
+    this.args.controller.setAnswer(question.id, { kind: "text", value: trimmed });
+    this.advanceAfterQuestion();
+  }
+
+  private applyChoiceSelection(
+    question: NormalizedChoiceQuestion,
+    optionIndex: number,
+    submit: boolean,
+  ): void {
+    if (question.multi) {
+      this.toggleMultiChoice(question, optionIndex);
+      if (submit && this.args.controller.hasAnswer(question.id)) this.advanceAfterQuestion();
+      return;
+    }
+
+    const option = question.options[optionIndex];
+    if (!option) return;
+    this.args.controller.setAnswer(question.id, {
+      kind: "choice",
+      selections: [{ value: option.value, label: option.label }],
+    });
+    this.choiceRowIndex = optionIndex;
+    this.previewOptionIndex = optionIndex;
+    if (submit) {
+      this.advanceAfterQuestion();
+      return;
+    }
+    this.buildChoiceList(question);
+    this.refresh();
+  }
+
+  private toggleMultiChoice(question: NormalizedChoiceQuestion, optionIndex: number): void {
+    const existing = new Set(this.args.controller.getSelectedIndexes(question));
+    if (existing.has(optionIndex)) existing.delete(optionIndex);
+    else existing.add(optionIndex);
+
+    const selections = [...existing]
+      .sort((left, right) => left - right)
+      .flatMap((index) => {
+        const option = question.options[index];
+        return option ? [{ value: option.value, label: option.label }] : [];
+      });
+
+    if (selections.length > 0) {
+      this.args.controller.setAnswer(question.id, { kind: "choice", selections });
+    } else {
+      this.args.controller.clearAnswer(question.id);
+    }
+    this.choiceRowIndex = optionIndex;
+    this.previewOptionIndex = optionIndex;
+    this.buildChoiceList(question);
+    this.refresh();
+  }
+
+  private handleAction(action: OverlayAction): void {
+    switch (action) {
+      case "other":
+        this.mode = "custom-input";
+        this.focus = "editor";
+        this.editor.setText(currentCustomValue(this.args.controller));
+        this.refresh();
+        return;
+      case "skip":
+        this.args.controller.clearAnswer(this.args.controller.currentQuestion.id);
+        this.advanceAfterQuestion();
+        return;
+      case "discuss":
+        this.mode = "discuss-input";
+        this.focus = "editor";
+        this.editor.setText("");
+        this.refresh();
+        return;
+      case "partial":
+        this.args.controller.finishPartial();
+        this.finish();
+        return;
+    }
+  }
+
+  private advanceAfterQuestion(): void {
+    if (!this.args.controller.goNext()) {
+      this.args.controller.finishSubmitted();
+      this.finish();
+      return;
+    }
+    this.syncCurrentQuestion();
+    this.refresh();
+  }
+
+  private syncCurrentQuestion(): void {
+    const question = this.args.controller.currentQuestion;
+    if (question.type === "text") {
+      this.mode = "text";
+      this.focus = "editor";
+      this.editor.setText(currentTextValue(this.args.controller, question.initial));
+      this.buildTextActions();
+      this.choiceRows = [];
+      this.choiceList = undefined;
+      return;
+    }
+
+    this.mode = "choice";
+    this.focus = "choices";
+    this.textActions = [];
+    this.actionList = undefined;
+    this.editor.setText("");
+    this.buildChoiceList(question);
+  }
+
+  private buildChoiceList(question: NormalizedChoiceQuestion): void {
+    this.choiceRows = buildChoiceRows(this.args.controller, question);
+    this.choiceRowIndex = clampIndex(
+      defaultChoiceRowIndex(this.args.controller, question, this.choiceRows),
+      this.choiceRows.length,
+    );
+    this.previewOptionIndex =
+      previewOptionIndexForRows(this.choiceRows, this.choiceRowIndex, this.previewOptionIndex) ?? 0;
+
+    const list = new SelectList(
+      buildChoiceItems(this.args.controller, question, this.choiceRows),
+      Math.min(this.choiceRows.length, 10),
+      makeSelectListTheme(this.args.theme),
+    );
+    list.onSelectionChange = (item) => {
+      const nextIndex = this.choiceRows.findIndex((row) => choiceRowValue(row) === item.value);
+      if (nextIndex < 0) return;
+      this.choiceRowIndex = nextIndex;
+      this.previewOptionIndex =
+        previewOptionIndexForRows(this.choiceRows, nextIndex, this.previewOptionIndex) ??
+        this.previewOptionIndex;
+      this.refresh();
+    };
+    list.onSelect = (item) => {
+      const row = this.choiceRows.find((candidate) => choiceRowValue(candidate) === item.value);
+      if (!row) return;
+      if (row.kind === "option") {
+        this.applyChoiceSelection(question, row.optionIndex, true);
+        return;
+      }
+      this.handleAction(row.action);
+    };
+    list.setSelectedIndex(this.choiceRowIndex);
+    this.choiceList = list;
+  }
+
+  private buildTextActions(): void {
+    const state = createActionList({
+      controller: this.args.controller,
+      theme: this.args.theme,
+      actionIndex: this.actionIndex,
+      onIndexChange: (index) => {
+        this.actionIndex = index;
+        this.refresh();
+      },
+      onAction: (action) => this.handleAction(action),
+    });
+    this.textActions = state.entries;
+    this.actionList = state.list;
+    this.actionIndex = state.index;
+  }
+
+  private refresh(): void {
+    this.cachedLines = undefined;
+    this.args.tui.requestRender();
+  }
+
+  private finish(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.args.signal?.removeEventListener("abort", this.onAbort);
+    this.args.done(this.args.controller.outcome());
+  }
+}

package/src/ui/types.ts

@@ -0,0 +1,35 @@
+import type { 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,
+      // biome-ignore lint/suspicious/noExplicitAny: keybindings are passed through by pi but unused here
+      keybindings: any,
+      done: (result: T) => void,
+    ) => Component & { dispose?(): void },
+  ): Promise<T>;
+}
+
+export interface RunQuestionnaireOptions {
+  ui: AskUserUiContext;
+  signal?: AbortSignal;
+}
+
+export interface RenderContext {
+  questionnaire: NormalizedQuestionnaire;
+  options: RunQuestionnaireOptions;
+}
+
+export interface OverlayArgs {
+  tui: TUI;
+  theme: Theme;
+  controller: AskUserController;
+  done: (result: AskUserOutcome) => void;
+  signal?: AbortSignal;
+}

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;
-}