@fitchmultz/pi-ask-question 0.6.5 → 0.6.7

package/extensions/lib/ask-dialogs.ts

@@ -0,0 +1,155 @@
+/** Dialog-mode ask flow for RPC UIs. */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { clean, orderedAnswers, uniqueOptionLabel } from "./normalize.ts";
+import {
+  CUSTOM_OPTION,
+  DONE_OPTION,
+  type Answer,
+  type NormalizedQuestion,
+  type QuestionResult,
+  type QuestionTimeout,
+} from "./types.ts";
+
+type DialogContext = {
+  ui: ExtensionContext["ui"];
+  timeout: QuestionTimeout;
+  signal: AbortSignal | undefined;
+};
+
+type DialogMenu = {
+  options: string[];
+  choices: string[];
+  customOption: string;
+  doneOption: string;
+};
+
+type DialogAnswer =
+  | { status: "retry" }
+  | { status: "cancel" }
+  | { status: "picked"; answer: string; wasCustom: boolean };
+
+/** Ask one question set through sequential select/input dialogs. */
+export async function askWithDialogs(
+  questions: NormalizedQuestion[],
+  ui: ExtensionContext["ui"],
+  timeout: QuestionTimeout,
+  signal: AbortSignal | undefined,
+): Promise<QuestionResult> {
+  const answers = new Map<string, Answer>();
+  for (const question of questions) {
+    if (signal?.aborted === true) {
+      return { answers: orderedAnswers(questions, answers), cancelled: true };
+    }
+    const cancelled = await askOneByDialog(question, answers, { ui, timeout, signal });
+    if (cancelled) {
+      return { answers: orderedAnswers(questions, answers), cancelled: true };
+    }
+  }
+  return { answers: orderedAnswers(questions, answers), cancelled: false };
+}
+
+async function askOneByDialog(
+  question: NormalizedQuestion,
+  answers: Map<string, Answer>,
+  context: DialogContext,
+): Promise<boolean> {
+  const selected: string[] = [];
+
+  while (true) {
+    const menu = buildDialogMenu(question, selected);
+    const choice = await context.ui.select(
+      question.question,
+      menu.choices,
+      ...(context.signal ? [{ signal: context.signal }] : []),
+    );
+    if (choice === undefined) {
+      return true;
+    }
+    context.timeout.stop();
+    if (choice === menu.doneOption) {
+      return false;
+    }
+
+    const resolved = await resolveDialogAnswer(question, menu, choice, context);
+    if (resolved.status === "cancel") {
+      return true;
+    }
+    if (resolved.status === "retry") {
+      continue;
+    }
+    applyDialogSelection(question, answers, selected, resolved);
+    if (!question.multiSelect) {
+      return false;
+    }
+  }
+}
+
+function buildDialogMenu(question: NormalizedQuestion, selected: string[]): DialogMenu {
+  const customOption = uniqueOptionLabel(CUSTOM_OPTION, question.options);
+  const doneOption = uniqueOptionLabel(DONE_OPTION, question.options);
+  const options = [
+    ...question.options,
+    ...selected.filter((answer) => !question.options.includes(answer)),
+  ];
+  const labels = question.multiSelect
+    ? options.map((answer) => `${selected.includes(answer) ? "☑" : "☐"} ${answer}`)
+    : options;
+  const choices = [...labels, customOption];
+  if (question.multiSelect && selected.length > 0) {
+    choices.push(doneOption);
+  }
+  return { options, choices, customOption, doneOption };
+}
+
+async function resolveDialogAnswer(
+  question: NormalizedQuestion,
+  menu: DialogMenu,
+  choice: string,
+  context: DialogContext,
+): Promise<DialogAnswer> {
+  if (choice !== menu.customOption) {
+    const answer = menu.options[menu.choices.indexOf(choice)] ?? choice;
+    return { status: "picked", answer, wasCustom: false };
+  }
+  const input = await context.ui.input(
+    question.question,
+    "Type your answer",
+    ...(context.signal ? [{ signal: context.signal }] : []),
+  );
+  if (input === undefined) {
+    return { status: "cancel" };
+  }
+  const custom = clean(input);
+  if (custom === undefined) {
+    return { status: "retry" };
+  }
+  return { status: "picked", answer: custom, wasCustom: true };
+}
+
+function applyDialogSelection(
+  question: NormalizedQuestion,
+  answers: Map<string, Answer>,
+  selected: string[],
+  picked: { answer: string; wasCustom: boolean },
+): void {
+  const index = selected.indexOf(picked.answer);
+  if (question.multiSelect && !picked.wasCustom && index !== -1) {
+    selected.splice(index, 1);
+  } else if (index === -1) {
+    selected.push(picked.answer);
+  }
+  if (selected.length === 0) {
+    answers.delete(question.id);
+    return;
+  }
+  answers.set(question.id, {
+    id: question.id,
+    question: question.question,
+    answer: question.multiSelect ? selected.join(", ") : picked.answer,
+    ...(question.multiSelect ? { selectedOptions: [...selected] } : {}),
+    wasCustom: question.multiSelect
+      ? selected.some((answer) => !question.options.includes(answer))
+      : picked.wasCustom,
+  });
+}

package/extensions/lib/ask-keyboard.ts

@@ -0,0 +1,55 @@
+/** Keyboard-mode ask flow: full-screen form plus cooperative-bus wiring. */
+
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { QuestionForm } from "./question-form.ts";
+import type { QuestionObserver } from "./question-observer.ts";
+import type { NormalizedQuestion, QuestionResult, QuestionTimeout } from "./types.ts";
+
+/** Ask through the full-screen keyboard UI with cooperative-bus support. */
+export async function askWithKeyboard(params: {
+  questions: NormalizedQuestion[];
+  ui: ExtensionContext["ui"];
+  pi: ExtensionAPI;
+  observer: QuestionObserver;
+  timeout: QuestionTimeout;
+  signal: AbortSignal | undefined;
+}): Promise<QuestionResult> {
+  const signal = params.signal;
+  if (signal?.aborted === true) {
+    return { answers: [], cancelled: true };
+  }
+  const promptId = randomUUID();
+  let form: QuestionForm | undefined;
+  return params.ui
+    .custom<QuestionResult>(
+      (tui, theme, keys, done) => {
+        form = new QuestionForm(
+          {
+            questions: params.questions,
+            promptId,
+            ui: params.ui,
+            pi: params.pi,
+            observer: params.observer,
+            timeout: params.timeout,
+            signal,
+            onDone: done,
+          },
+          tui,
+          theme,
+          keys,
+        );
+        return form;
+      },
+      {
+        overlay: true,
+        overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" },
+        onHandle: (handle) => {
+          form?.attachOverlay(handle);
+        },
+      },
+    )
+    .finally(() => {
+      form?.release();
+    });
+}

package/extensions/lib/form-answers.ts

@@ -0,0 +1,86 @@
+/** Answer bookkeeping for the question form: single, multi-select, and custom answers. */
+
+import { orderedAnswers } from "./normalize.ts";
+import type { Answer, NormalizedQuestion } from "./types.ts";
+
+/** The answer model for one prompt; the form orchestrates view updates around it. */
+export class AnswerSheet {
+  readonly answers = new Map<string, Answer>();
+  private readonly multi = new Map<string, Set<string>>();
+  readonly custom = new Map<string, string>();
+
+  has(questionId: string): boolean {
+    return this.answers.has(questionId);
+  }
+
+  get(questionId: string): Answer | undefined {
+    return this.answers.get(questionId);
+  }
+
+  ordered(questions: NormalizedQuestion[]): Answer[] {
+    return orderedAnswers(questions, this.answers);
+  }
+
+  selectedSet(question: NormalizedQuestion): Set<string> {
+    let selected = this.multi.get(question.id);
+    if (selected === undefined) {
+      selected = new Set<string>();
+      this.multi.set(question.id, selected);
+    }
+    return selected;
+  }
+
+  /** Write the joined multi-select answer; deletes it when nothing is selected. */
+  syncMultiAnswer(question: NormalizedQuestion): void {
+    const selected = [...this.selectedSet(question)];
+    if (selected.length === 0) {
+      this.answers.delete(question.id);
+      return;
+    }
+    this.answers.set(question.id, {
+      id: question.id,
+      question: question.question,
+      answer: selected.join(", "),
+      selectedOptions: selected,
+      wasCustom: selected.some((answer) => !question.options.includes(answer)),
+    });
+  }
+
+  toggleMultiChoice(question: NormalizedQuestion, choice: string): void {
+    const selected = this.selectedSet(question);
+    if (selected.has(choice)) {
+      selected.delete(choice);
+    } else {
+      selected.add(choice);
+    }
+  }
+
+  setMultiCustom(question: NormalizedQuestion, answer: string): void {
+    const selected = this.selectedSet(question);
+    const previous = this.custom.get(question.id);
+    if (previous !== undefined) {
+      selected.delete(previous);
+    }
+    this.custom.set(question.id, answer);
+    selected.add(answer);
+  }
+
+  setSingle(question: NormalizedQuestion, answer: string, wasCustom: boolean): void {
+    this.answers.set(question.id, {
+      id: question.id,
+      question: question.question,
+      answer,
+      wasCustom,
+    });
+  }
+
+  /** Replace the multi-select choices and forget any custom answer. */
+  applyOptions(question: NormalizedQuestion, choices: string[]): void {
+    const selected = this.selectedSet(question);
+    selected.clear();
+    this.custom.delete(question.id);
+    for (const choice of choices) {
+      selected.add(choice);
+    }
+  }
+}

package/extensions/lib/form-page.ts

@@ -0,0 +1,411 @@
+/** Page layout for the question form: line accumulation and section bounds. */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  CURSOR_MARKER,
+  Editor,
+  sliceByColumn,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Keybinding,
+  type OverlayHandle,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { formatAnswer } from "./normalize.ts";
+import { wrapByColumn } from "./text.ts";
+import type { Answer, NormalizedQuestion } from "./types.ts";
+
+/** Read-only form surface the page builders render from. */
+export type FormView = {
+  readonly questions: NormalizedQuestion[];
+  readonly answers: Map<string, Answer>;
+  readonly customAnswers: Map<string, string>;
+  readonly tab: number;
+  readonly option: number;
+  readonly editing: boolean;
+  readonly showTabs: boolean;
+  readonly submitTab: number;
+  readonly timeoutActive: boolean;
+  readonly theme: Theme;
+  keyText: (binding: Keybinding) => string;
+  current: () => NormalizedQuestion | undefined;
+  choices: () => string[];
+  customOption: () => string;
+  allAnswered: () => boolean;
+  selectedSet: (question: NormalizedQuestion) => Set<string>;
+  renderEditor: (width: number) => string[];
+};
+
+/** Accumulates rendered lines while tracking page-section bounds. */
+export class PageBuilder {
+  readonly width: number;
+  readonly lines: string[] = [];
+  readonly optionRows: Array<{ start: number; end: number }> = [];
+  questionStart = 0;
+  questionEnd = 0;
+  optionStart = 0;
+  optionEnd = 0;
+  reviewStart = 0;
+  reviewEnd = 0;
+  contextHint = "";
+
+  constructor(width: number) {
+    this.width = width;
+  }
+
+  get length(): number {
+    return this.lines.length;
+  }
+
+  add(line = ""): void {
+    this.lines.push(
+      visibleWidth(line) > this.width ? sliceByColumn(line, 0, this.width, true) : line,
+    );
+  }
+
+  beginQuestion(): void {
+    this.questionStart = this.lines.length;
+  }
+
+  endQuestion(): void {
+    this.questionEnd = this.lines.length;
+  }
+
+  beginOptions(): void {
+    this.optionStart = this.lines.length;
+  }
+
+  endOptions(): void {
+    this.optionEnd = this.lines.length;
+  }
+
+  beginReview(): void {
+    this.reviewStart = this.lines.length;
+  }
+
+  endReview(): void {
+    this.reviewEnd = this.lines.length;
+  }
+
+  pushOptionRow(start: number): void {
+    this.optionRows.push({ start, end: this.lines.length - this.optionStart });
+  }
+
+  setLine(index: number, line: string): void {
+    this.lines[index] = line;
+  }
+
+  setContextHint(hint: string): void {
+    this.contextHint = hint;
+  }
+
+  /** Drop clipped rows and shift the option section up by the removed count. */
+  shiftOptions(removed: number): void {
+    this.optionStart -= removed;
+    this.optionEnd -= removed;
+  }
+}
+
+type WrapOptions = {
+  firstPrefix?: string;
+  restPrefix?: string;
+  style?: (text: string) => string;
+  prefixStyle?: (text: string) => string;
+  preserveWhitespace?: boolean;
+};
+
+type ResolvedWrap = {
+  firstPrefix: string;
+  restPrefix: string;
+  style: (text: string) => string;
+  prefixStyle: (text: string) => string;
+  preserveWhitespace: boolean;
+};
+
+function resolveWrapOptions(options: WrapOptions): ResolvedWrap {
+  return {
+    firstPrefix: options.firstPrefix ?? "",
+    restPrefix: options.restPrefix ?? "",
+    style: options.style ?? ((value: string) => value),
+    prefixStyle: options.prefixStyle ?? ((value: string) => value),
+    preserveWhitespace: options.preserveWhitespace === true,
+  };
+}
+
+/** Append wrapped text with optional prefixes and styling. */
+export function addWrapped(
+  page: PageBuilder,
+  view: FormView,
+  text: string,
+  options: WrapOptions = {},
+): void {
+  const resolved = resolveWrapOptions(options);
+  const wrap = resolved.preserveWhitespace ? wrapByColumn : wrapTextWithAnsi;
+  const prefixWidth = visibleWidth(resolved.firstPrefix);
+  if (prefixWidth >= page.width || (resolved.preserveWhitespace && page.width - prefixWidth < 2)) {
+    for (const line of wrap(
+      `${resolved.prefixStyle(resolved.firstPrefix)}${resolved.style(text)}`,
+      page.width,
+    )) {
+      page.add(line);
+    }
+    return;
+  }
+  const wrapped = wrap(resolved.style(text), page.width - prefixWidth);
+  page.add(`${resolved.prefixStyle(resolved.firstPrefix)}${wrapped[0] ?? ""}`);
+  for (let index = 1; index < wrapped.length; index += 1) {
+    page.add(`${resolved.prefixStyle(resolved.restPrefix)}${wrapped[index] ?? ""}`);
+  }
+}
+
+/** Build the full page for the current form state. */
+export function buildFormPage(view: FormView, width: number): PageBuilder {
+  const page = new PageBuilder(width);
+  page.add(view.theme.fg("accent", "─".repeat(page.width)));
+  if (view.showTabs && !view.editing) {
+    addTabRow(page, view);
+  }
+  if (view.tab === view.submitTab) {
+    addReviewPage(page, view);
+  } else {
+    addQuestionPage(page, view);
+  }
+  addFooter(page, view);
+  return page;
+}
+
+/** The single-line hint shown while the user reads the conversation. */
+export function contextHint(theme: Theme, width: number): { line: string; width: number } {
+  const hint = truncateToWidth("ctrl+o return to question • scroll conversation", width, "…");
+  return { line: theme.fg("dim", hint), width: visibleWidth(hint) };
+}
+
+/** Tracks ctrl+o context-reading mode: overlay focus handoff and hint hit-testing. */
+export class ContextReader {
+  private active = false;
+  private hintStart = 0;
+  private hintEnd = 0;
+  private hintWidth = 0;
+
+  get reading(): boolean {
+    return this.active;
+  }
+
+  contains(event: { x: number; y: number }): boolean {
+    return event.y >= this.hintStart && event.y < this.hintEnd && event.x < this.hintWidth;
+  }
+
+  toggle(overlay: OverlayHandle | undefined): void {
+    this.active = !this.active;
+    if (this.active) {
+      overlay?.unfocus({ target: null });
+    } else {
+      overlay?.focus();
+    }
+  }
+
+  renderHint(theme: Theme, width: number): string[] {
+    const hint = contextHint(theme, width);
+    this.hintStart = 0;
+    this.hintEnd = 1;
+    this.hintWidth = hint.width;
+    return [hint.line];
+  }
+
+  trackHint(page: PageBuilder): void {
+    this.hintStart = page.lines.length - 1;
+    this.hintEnd = page.lines.length;
+    this.hintWidth = visibleWidth(page.contextHint);
+  }
+}
+
+/** The inline editor for typed custom answers. */
+export function createPromptEditor(tui: TUI, theme: Theme): Editor {
+  return new Editor(tui, {
+    borderColor: (text) => theme.fg("accent", text),
+    selectList: {
+      selectedPrefix: (text) => theme.fg("accent", text),
+      selectedText: (text) => theme.fg("accent", text),
+      description: (text) => theme.fg("muted", text),
+      scrollInfo: (text) => theme.fg("dim", text),
+      noMatch: (text) => theme.fg("warning", text),
+    },
+  });
+}
+
+/** Reserve terminal rows below the form overlay so the transcript does not shift. */
+export function reserveWidgetRows(
+  ui: ExtensionContext["ui"],
+  widgetKey: string,
+  reservedRows: () => number,
+): void {
+  ui.setWidget(widgetKey, () => ({
+    render: () => Array.from({ length: reservedRows() }, () => ""),
+    invalidate() {
+      // The spacer has no cached output to invalidate.
+    },
+  }));
+}
+
+function addTabRow(page: PageBuilder, view: FormView): void {
+  const labels = [
+    ...view.questions.map((question, index) => {
+      const marker = view.answers.has(question.id) ? "■" : "□";
+      const label = ` ${marker} Q${index + 1} `;
+      return index === view.tab
+        ? view.theme.bg("selectedBg", view.theme.fg("text", label))
+        : view.theme.fg("muted", label);
+    }),
+    view.tab === view.submitTab
+      ? view.theme.bg("selectedBg", view.theme.fg("text", " Submit "))
+      : view.theme.fg(view.allAnswered() ? "success" : "dim", " Submit "),
+  ].join(" ");
+  addWrapped(page, view, labels);
+  page.add();
+}
+
+function addReviewPage(page: PageBuilder, view: FormView): void {
+  addWrapped(page, view, view.theme.bold("Review answers"));
+  page.add();
+  page.beginReview();
+  for (const question of view.questions) {
+    const answer = view.answers.get(question.id);
+    addWrapped(page, view, formatAnswer(answer), {
+      firstPrefix: `${question.id}: `,
+      restPrefix: " ".repeat(visibleWidth(`${question.id}: `)),
+      ...(answer ? {} : { style: (text: string) => view.theme.fg("warning", text) }),
+      preserveWhitespace: answer?.selectedOptions !== undefined,
+    });
+  }
+  page.endReview();
+  page.add();
+  addWrapped(
+    page,
+    view,
+    view.allAnswered()
+      ? `${view.keyText("tui.select.confirm")} to submit`
+      : "Answer all questions before submitting",
+    {
+      style: (text) => view.theme.fg(view.allAnswered() ? "success" : "warning", text),
+    },
+  );
+}
+
+function addQuestionPage(page: PageBuilder, view: FormView): void {
+  const question = view.current();
+  if (question === undefined) {
+    return;
+  }
+  const answer = view.answers.get(question.id);
+  page.beginQuestion();
+  addWrapped(
+    page,
+    view,
+    question.multiSelect ? `${question.question} (select one or more)` : question.question,
+  );
+  page.endQuestion();
+  page.add();
+  page.beginOptions();
+  addOptionRows(page, view, question);
+  page.endOptions();
+  if (answer !== undefined && !view.editing) {
+    addAnswerPreview(page, view, question, answer);
+  }
+  if (view.editing) {
+    addEditorLines(page, view);
+  }
+}
+
+function addOptionRows(page: PageBuilder, view: FormView, question: NormalizedQuestion): void {
+  for (const [index, choice] of view.choices().entries()) {
+    if (view.editing && index !== view.option) {
+      continue;
+    }
+    const start = page.length - page.optionStart;
+    const highlighted = index === view.option;
+    const checked = question.multiSelect ? view.selectedSet(question).has(choice) : false;
+    let marker: string;
+    if (!question.multiSelect) {
+      marker = `${index + 1}.`;
+    } else if (choice === view.customOption()) {
+      marker = "✎";
+    } else {
+      marker = checked ? "☑" : "☐";
+    }
+    const prefix = `${highlighted ? ">" : " "} ${marker} `;
+    addWrapped(page, view, choice, {
+      firstPrefix: prefix,
+      restPrefix: " ".repeat(prefix.length),
+      style: (text) => view.theme.fg(highlighted ? "accent" : "text", text),
+      prefixStyle: (text) =>
+        highlighted && text.includes(">") ? view.theme.fg("accent", text) : text,
+    });
+    page.pushOptionRow(start);
+  }
+}
+
+function addAnswerPreview(
+  page: PageBuilder,
+  view: FormView,
+  question: NormalizedQuestion,
+  answer: Answer,
+): void {
+  const custom = question.multiSelect ? view.customAnswers.get(question.id) : undefined;
+  const selected = question.multiSelect ? view.selectedSet(question) : undefined;
+  let summary = answer.answer;
+  if (custom !== undefined && selected !== undefined && selected.has(custom)) {
+    summary = `${custom} (${selected.size} selected)`;
+  }
+  const preview = `Current answer: ${summary.replace(/\s+/g, " ")}`;
+  page.add(view.theme.fg("muted", truncateToWidth(preview, page.width, "…")));
+}
+
+function addEditorLines(page: PageBuilder, view: FormView): void {
+  addWrapped(page, view, view.theme.fg("muted", "Your answer:"));
+  const indent = page.width > 1 ? " " : "";
+  const editorWidth = Math.max(1, page.width - visibleWidth(indent));
+  for (const line of view.renderEditor(Math.max(3, editorWidth))) {
+    const cursorIndex = line.indexOf(CURSOR_MARKER);
+    const cursorColumn = cursorIndex === -1 ? 0 : visibleWidth(line.slice(0, cursorIndex));
+    const startColumn = Math.max(0, cursorColumn - editorWidth + 1);
+    page.add(`${indent}${sliceByColumn(line, startColumn, editorWidth, true)}`);
+  }
+}
+
+function footerHints(view: FormView): string {
+  if (view.editing) {
+    return `${view.keyText("tui.input.submit")} save answer • ${view.keyText("tui.select.cancel")} cancel edit`;
+  }
+  if (view.showTabs) {
+    return `←/→ or ${view.keyText("tui.input.tab")} questions • ${view.keyText("tui.select.up")}/${view.keyText("tui.select.down")} options • Space toggle multi-select • ${view.keyText("tui.select.confirm")} next/submit • ${view.keyText("tui.select.cancel")} cancel`;
+  }
+  return `${view.keyText("tui.select.up")}/${view.keyText("tui.select.down")} options • ${view.keyText("tui.select.confirm")} select • ${view.keyText("tui.select.cancel")} cancel`;
+}
+
+function addFooter(page: PageBuilder, view: FormView): void {
+  if (!view.editing) {
+    page.add();
+  }
+  addWrapped(
+    page,
+    view,
+    view.timeoutActive
+      ? "Auto-continues after 5 minutes without interaction."
+      : "No time limit while you answer.",
+    {
+      style: (text) => view.theme.fg("dim", text),
+    },
+  );
+  addWrapped(page, view, footerHints(view), {
+    style: (text) => view.theme.fg("dim", text),
+  });
+  const hint = truncateToWidth("ctrl+o read context", page.width, "…");
+  page.add(
+    `${view.theme.fg("dim", hint)}${view.theme.fg(
+      "accent",
+      "─".repeat(Math.max(0, page.width - visibleWidth(hint))),
+    )}`,
+  );
+  page.setContextHint(hint);
+}