surgent 0.7.0-alpha.0

package/src/questionnaire/component.ts

@@ -0,0 +1,357 @@
+import {
+  Editor,
+  Key,
+  matchesKey,
+  parseKey,
+  wrapTextWithAnsi,
+  type EditorTheme,
+  type Focusable,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { type Theme } from "@earendil-works/pi-coding-agent";
+import { Frame } from "../ui/components/frame.js";
+import { Lines } from "../ui/components/lines.js";
+import {
+  createInitialDraft,
+  ensureSingleSelection,
+  getValidationMessage,
+  moveCursor,
+  serializeQuestionAnswer,
+  summarizeAnswer,
+  toggleSuggestion,
+} from "./helpers.js";
+import type { NormalizedQuestion, QuestionDraft, QuestionnaireResult } from "./types.js";
+
+export default class Questionnaire extends Frame implements Focusable {
+  onDone?: (result: QuestionnaireResult) => void;
+
+  private readonly drafts: QuestionDraft[];
+  private readonly editors: Editor[] = [];
+
+  private tab = 0;
+  private _focused = false;
+
+  constructor(
+    private readonly tui: TUI,
+    protected theme: Theme,
+    private readonly questions: NormalizedQuestion[],
+  ) {
+    super(theme);
+    this.drafts = questions.map((question) => createInitialDraft(question));
+    this.questions.forEach((_, index) => {
+      const editor = this.createEditor();
+      editor.onChange = () => {
+        const draft = this.drafts[index]!;
+        draft.text = editor.getText();
+      };
+      this.editors.push(editor);
+    });
+
+    this.registerKeybindings([
+      {
+        key: Key.escape,
+        hint: "cancel",
+        handler: () => this.onDone?.({ cancelled: true, questions: [], answers: [] }),
+      },
+      {
+        key: { navigation: "horizontal", metakey: Key.alt },
+        hint: "switch tabs",
+        navigate: (keyId) => this.moveQuestion(keyId === Key.left ? -1 : 1),
+      },
+      {
+        key: { navigation: "vertical" },
+        hint: "focus options",
+        navigate: (keyId) => this.handleVerticalNav(keyId),
+      },
+      { key: Key.tab, hint: "switch focus", handler: () => this.toggleFocusMode() },
+      { key: Key.space, hint: "toggle option", handler: () => this.toggleOption() },
+      { key: Key.enter, hint: "continue", handler: () => this.handleEnterKey() },
+    ]);
+    this.syncInteractionState();
+  }
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.syncEditorFocus();
+  }
+
+  invalidate() {
+    for (const editor of this.editors) editor.invalidate();
+  }
+
+  handleInput(data: string) {
+    if (this.handleKb(data)) return;
+    if (this.tab === this.questions.length) return;
+    if (!this.drafts[this.tab]!.editing) {
+      const parsedKey = parseKey(data);
+      const shouldRouteToEditor =
+        (parsedKey !== undefined && parsedKey.length === 1) ||
+        matchesKey(data, Key.backspace) ||
+        matchesKey(data, Key.delete) ||
+        matchesKey(data, Key.space);
+      if (!shouldRouteToEditor) return;
+      this.setEditing(true);
+    }
+    this.editors[this.tab]!.handleInput(data);
+  }
+
+  protected override children(width: number) {
+    const lines = new Lines(width);
+
+    lines.add(this.renderTabs());
+    lines.space();
+
+    if (this.tab === this.questions.length) {
+      lines.add(this.theme.bold("Review answers"));
+      lines.space();
+      for (const [index, question] of this.questions.entries()) {
+        const answer = serializeQuestionAnswer(question, this.drafts[index]!);
+        for (const line of wrapTextWithAnsi(`Q${index + 1}: ${question.prompt}`, width)) {
+          lines.add(line);
+        }
+        for (const line of wrapTextWithAnsi(`A${index + 1}: ${answer || "(incomplete)"}`, width)) {
+          lines.add(this.theme.fg("accent", line));
+        }
+        if (index < this.questions.length - 1) lines.space();
+      }
+      lines.space();
+      lines.add(
+        this.theme.fg(
+          this.allQuestionsAnswered() ? "success" : "warning",
+          this.allQuestionsAnswered()
+            ? "Press Enter to submit."
+            : "Complete required answers before submitting.",
+        ),
+      );
+      return lines.get();
+    }
+
+    const question = this.questions[this.tab]!;
+    const draft = this.drafts[this.tab]!;
+    const editor = this.editors[this.tab]!;
+
+    for (const wrappedPromptLine of wrapTextWithAnsi(this.theme.bold(question.prompt), width)) {
+      lines.add(wrappedPromptLine);
+    }
+    if (question.reason) {
+      for (const wrappedLine of wrapTextWithAnsi(this.theme.fg("muted", question.reason), width)) {
+        lines.add(wrappedLine);
+      }
+    }
+
+    if (question.options.length > 0) {
+      lines.space();
+      lines.add(
+        this.theme.fg(
+          draft.editing ? "muted" : "accent",
+          `Options ${draft.editing ? "[press Tab or ↑↓]" : "[selecting]"}`,
+        ),
+      );
+      lines.space();
+      for (const [index, option] of question.options.entries()) {
+        const selected = draft.selectedIndexes.includes(index);
+        const cursor = draft.cursor === index && !draft.editing;
+        const marker = question.multi ? (selected ? "[x]" : "[ ]") : selected ? "(*)" : "( )";
+        const prefix = cursor ? this.theme.fg("accent", "→") : " ";
+        const recommendation =
+          question.recommendedCount !== undefined && index < question.recommendedCount
+            ? this.theme.fg("success", " [recommended]")
+            : "";
+        const exclusive = option.exclusive ? this.theme.fg("dim", " [exclusive]") : "";
+        const optionText = `${marker} ${option.text}${recommendation}${exclusive}`;
+        lines.add(`${prefix} ${cursor ? this.theme.fg("accent", optionText) : optionText}`);
+        if (option.description) lines.add(this.theme.fg("muted", option.description), 6);
+      }
+    }
+
+    lines.space();
+    lines.add(
+      this.theme.fg(
+        draft.editing ? "accent" : "muted",
+        `${question.placeholder} ${draft.editing ? "[editing]" : "[press Tab to edit]"}`,
+      ),
+    );
+    for (const line of editor.render(Math.max(12, width - 2))) lines.add(line);
+
+    const currentAnswer = serializeQuestionAnswer(question, draft);
+    lines.space();
+    lines.add(`${this.theme.fg("success", "Answer:")} ${summarizeAnswer(currentAnswer)}`);
+
+    return lines.get();
+  }
+
+  private createEditor(): Editor {
+    const editorTheme: EditorTheme = {
+      borderColor: (text) => this.theme.fg("dim", text),
+      selectList: {
+        selectedPrefix: (text) => this.theme.fg("accent", text),
+        selectedText: (text) => this.theme.fg("accent", text),
+        description: (text) => this.theme.fg("muted", text),
+        scrollInfo: (text) => this.theme.fg("dim", text),
+        noMatch: (text) => this.theme.fg("warning", text),
+      },
+    };
+    return new Editor(this.tui, editorTheme);
+  }
+
+  private moveQuestion(delta: number) {
+    this.tab = Math.max(0, Math.min(this.questions.length, this.tab + delta));
+    this.syncInteractionState();
+  }
+
+  private setEditing(editing: boolean) {
+    const draft = this.drafts[this.tab]!;
+    if (draft.editing === editing) return;
+    draft.editing = editing;
+    this.syncInteractionState();
+  }
+
+  private toggleFocusMode() {
+    if (this.questions[this.tab]!.options.length === 0) return;
+    this.setEditing(!this.drafts[this.tab]!.editing);
+  }
+
+  private handleVerticalNav(keyId: string) {
+    const question = this.questions[this.tab]!;
+    if (question.options.length === 0) return;
+
+    const draft = this.drafts[this.tab]!;
+    const oldCursor = draft.cursor;
+
+    if (keyId === Key.down) {
+      moveCursor(question, draft, 1);
+      if (draft.cursor === oldCursor) {
+        this.setEditing(true);
+      }
+      return;
+    }
+
+    moveCursor(question, draft, draft.editing ? 0 : -1);
+    this.setEditing(false);
+  }
+
+  private toggleOption() {
+    const question = this.questions[this.tab]!;
+    const draft = this.drafts[this.tab]!;
+    if (!question.multi || draft.editing) return;
+
+    const result = toggleSuggestion(question, draft, draft.cursor);
+    this.drafts[this.tab] = { ...draft, selectedIndexes: result.selectedIndexes };
+  }
+
+  private handleEnterKey() {
+    if (this.tab === this.questions.length) {
+      this.submitAnswer();
+      return;
+    }
+
+    const question = this.questions[this.tab]!;
+    const draft = this.drafts[this.tab]!;
+    if (question.options.length > 0 && !draft.editing && !question.multi) {
+      this.drafts[this.tab] = { ...draft, selectedIndexes: [draft.cursor] };
+    }
+    this.submitAnswer();
+  }
+
+  private submitAnswer() {
+    if (this.tab === this.questions.length) {
+      if (!this.allQuestionsAnswered()) {
+        this.tab = this.firstIncompleteIndex();
+        this.syncInteractionState();
+        return;
+      }
+
+      this.onDone?.({
+        cancelled: false,
+        questions: this.questions.map((entry) => entry.prompt),
+        answers: this.questions.map((entry, index) =>
+          serializeQuestionAnswer(entry, this.drafts[index]!),
+        ),
+      });
+      return;
+    }
+
+    const question = this.questions[this.tab]!;
+    const draft = this.drafts[this.tab]!;
+    ensureSingleSelection(question, this.drafts[this.tab]!);
+
+    const message = getValidationMessage(question, draft);
+    if (message) {
+      return;
+    }
+    this.tab += 1;
+    this.syncInteractionState();
+  }
+
+  private allQuestionsAnswered(): boolean {
+    return this.questions.every(
+      (question, index) => !getValidationMessage(question, this.drafts[index]!),
+    );
+  }
+
+  private firstIncompleteIndex(): number {
+    const index = this.questions.findIndex(
+      (question, index) => !!getValidationMessage(question, this.drafts[index]!),
+    );
+    return index >= 0 ? index : this.questions.length - 1;
+  }
+
+  private renderTabs(): string {
+    const tabs = this.questions.map((question, index) => {
+      const answered = !getValidationMessage(question, this.drafts[index]!);
+      const label = ` Q${index + 1}${answered ? "*" : ""} `;
+      if (index === this.tab) {
+        return this.theme.bg("selectedBg", this.theme.fg("text", label));
+      }
+      return this.theme.fg(answered ? "success" : "muted", label);
+    });
+    const submitLabel = " Submit ";
+    tabs.push(
+      this.tab === this.questions.length
+        ? this.theme.bg("selectedBg", this.theme.fg("text", submitLabel))
+        : this.theme.fg(this.allQuestionsAnswered() ? "success" : "muted", submitLabel),
+    );
+    return tabs.join(" ");
+  }
+
+  private syncInteractionState() {
+    this.syncEditorFocus();
+    this.syncKeybindingState();
+  }
+
+  private syncKeybindingState() {
+    this.setArrowKeyAccess({ navigation: "horizontal", metakey: Key.alt }, true);
+
+    if (this.tab === this.questions.length) {
+      this.setArrowKeyAccess({ navigation: "vertical" }, false);
+      this.setKeyAccess(Key.tab, false);
+      this.setKeyAccess(Key.space, false);
+      this.setHint(Key.enter, "submit");
+      return;
+    }
+
+    const question = this.questions[this.tab]!;
+    const draft = this.drafts[this.tab]!;
+    const hasOptions = question.options.length > 0;
+    const optionsFocused = hasOptions && !draft.editing;
+
+    this.setArrowKeyAccess({ navigation: "vertical" }, hasOptions);
+    this.setKeyAccess(Key.tab, hasOptions);
+    this.setKeyAccess(Key.space, optionsFocused && question.multi);
+
+    this.setHint(Key.tab, optionsFocused ? "edit answer" : "select options");
+    this.setHint(Key.up, optionsFocused ? "move options" : "focus options");
+    this.setHint(Key.enter, optionsFocused && !question.multi ? "select + continue" : "continue");
+  }
+
+  private syncEditorFocus() {
+    for (const [index, editor] of this.editors.entries()) {
+      const draft = this.drafts[index]!;
+      editor.focused = this.focused && index === this.tab && draft.editing;
+    }
+  }
+}

package/src/questionnaire/helpers.ts

@@ -0,0 +1,220 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import Questionnaire from "./component.js";
+import type {
+  NormalizedQuestion,
+  Question,
+  QuestionDraft,
+  QuestionnaireResult,
+  QuestionOption,
+  ToggleSelectionResult,
+} from "./types.js";
+
+export function createInitialDraft(question: NormalizedQuestion): QuestionDraft {
+  const selectedIndexes = question.multi
+    ? question.options.slice(0, question.recommendedCount).map((_option, index) => index)
+    : [];
+
+  return {
+    text: "",
+    selectedIndexes,
+    cursor: selectedIndexes[0] ?? 0,
+    editing: question.options.length === 0,
+  };
+}
+
+export function getValidationMessage(
+  question: NormalizedQuestion,
+  draft: QuestionDraft,
+): string | undefined {
+  const trimmedText = draft.text.trim();
+  const selectedCount = draft.selectedIndexes.length;
+
+  if (question.multi && selectedCount > question.maxSelections) {
+    return `Select at most ${question.maxSelections} option${question.maxSelections === 1 ? "" : "s"}, or type your answer.`;
+  }
+  if (trimmedText) {
+    return;
+  }
+  if (question.options.length === 0) {
+    return "Type an answer to continue.";
+  }
+  if (!question.multi) {
+    return selectedCount > 0 ? undefined : "Select a option or type an answer to continue.";
+  }
+  if (selectedCount === 0) {
+    return "Select one or more options, or type an answer to continue.";
+  }
+  if (selectedCount < question.minSelections) {
+    return `Select at least ${question.minSelections} option${question.minSelections === 1 ? "" : "s"}, or type an answer.`;
+  }
+  return;
+}
+
+export function serializeQuestionAnswer(
+  question: NormalizedQuestion,
+  draft: QuestionDraft,
+): string {
+  const trimmedText = draft.text.trim();
+  const selectedTexts = draft.selectedIndexes
+    .map((index) => question.options[index]?.text)
+    .filter((value): value is string => Boolean(value));
+
+  if (!question.multi) {
+    return trimmedText || selectedTexts[0] || "";
+  }
+
+  const lines: string[] = [];
+
+  for (const text of selectedTexts) {
+    if (!lines.includes(text)) {
+      lines.push(text);
+    }
+  }
+
+  if (trimmedText && !lines.includes(trimmedText)) {
+    lines.push(trimmedText);
+  }
+
+  return lines.join("\n");
+}
+
+export function summarizeAnswer(answer: string): string {
+  return answer.replace(/\s*\n\s*/g, " / ").trim();
+}
+
+export function toggleSuggestion(
+  question: NormalizedQuestion,
+  draft: QuestionDraft,
+  optionIndex: number,
+): ToggleSelectionResult {
+  if (!question.multi) {
+    return { selectedIndexes: [optionIndex] };
+  }
+
+  const option = question.options[optionIndex];
+  if (!option) {
+    return { selectedIndexes: draft.selectedIndexes };
+  }
+
+  const currentlySelected = draft.selectedIndexes.includes(optionIndex);
+  if (currentlySelected) {
+    return {
+      selectedIndexes: draft.selectedIndexes.filter((index) => index !== optionIndex),
+    };
+  }
+
+  if (option.exclusive) {
+    return { selectedIndexes: [optionIndex] };
+  }
+
+  const withoutExclusive = draft.selectedIndexes.filter(
+    (index) => !question.options[index]?.exclusive,
+  );
+  if (withoutExclusive.length >= question.maxSelections) {
+    return {
+      selectedIndexes: draft.selectedIndexes,
+      message: `Select at most ${question.maxSelections} option${question.maxSelections === 1 ? "" : "s"}.`,
+    };
+  }
+
+  return { selectedIndexes: [...withoutExclusive, optionIndex] };
+}
+
+export function ensureSingleSelection(question: NormalizedQuestion, draft: QuestionDraft) {
+  if (question.multi || question.options.length === 0) return draft;
+  draft.selectedIndexes = [draft.cursor];
+}
+
+export function moveCursor(question: NormalizedQuestion, draft: QuestionDraft, delta: number) {
+  if (question.options.length === 0) return draft;
+  draft.cursor = Math.max(0, Math.min(question.options.length - 1, draft.cursor + delta));
+}
+
+export async function askQuestions(questions: Question[], ui: ExtensionUIContext) {
+  if (questions.length === 0) {
+    throw new Error("At least one question is required.");
+  }
+
+  const normalized = questions.map(normalizeQuestion);
+  return ui.custom<QuestionnaireResult>((tui, theme, _keybindings, done) => {
+    const component = new Questionnaire(tui, theme, normalized);
+    component.onDone = done;
+    return component;
+  });
+}
+
+function normalizeQuestion(question: Question): NormalizedQuestion {
+  const prompt = question.prompt.trim();
+  if (!prompt) {
+    throw new Error("Question prompt must not be empty.");
+  }
+
+  const options = question.options ?? [];
+  const multi = question.multi === true && options.length > 0;
+  const minSelections = multi ? (question.minSelections ?? 1) : 1;
+  const maxSelections = multi ? (question.maxSelections ?? options.length) : 1;
+  const recommendedCount = getRecommendedCount({
+    options,
+    multi,
+    minSelections,
+    recommendedCount: question.recommendedCount,
+  });
+
+  if (multi && options.length === 0) {
+    throw new Error(`Question "${prompt}" enables multi-select but does not provide any options.`);
+  }
+  if (multi && maxSelections < minSelections) {
+    throw new Error(`Question "${prompt}" has minSelections greater than maxSelections.`);
+  }
+  if (multi && maxSelections > options.length) {
+    throw new Error(`Question "${prompt}" has maxSelections larger than the number of options.`);
+  }
+  if (
+    !multi &&
+    options.length > 0 &&
+    question.recommendedCount !== undefined &&
+    question.recommendedCount !== 1
+  ) {
+    throw new Error(`Question "${prompt}" must use recommendedCount: 1 for single-select options.`);
+  }
+  if (multi && recommendedCount !== undefined && recommendedCount < minSelections) {
+    throw new Error(
+      `Question "${prompt}" must have recommendedCount greater than or equal to minSelections.`,
+    );
+  }
+  if (recommendedCount !== undefined && recommendedCount > options.length) {
+    throw new Error(`Question "${prompt}" has recommendedCount larger than the number of options.`);
+  }
+  if (options.length > 0 && recommendedCount === undefined) {
+    throw new Error(
+      `Question "${prompt}" must provide recommended options at the top of the list.`,
+    );
+  }
+  if (options.length > 0 && recommendedCount !== undefined && recommendedCount < 1) {
+    throw new Error(
+      `Question "${prompt}" must recommend at least one option when options are provided.`,
+    );
+  }
+
+  return {
+    prompt,
+    reason: question.reason?.trim(),
+    options,
+    placeholder: question.placeholder.trim(),
+    multi,
+    recommendedCount,
+    minSelections,
+    maxSelections,
+  };
+}
+
+function getRecommendedCount(question: {
+  options: QuestionOption[];
+  multi: boolean;
+  minSelections: number;
+  recommendedCount?: number;
+}): number | undefined {
+  if (question.options.length === 0) return;
+  if (!question.multi) return 1;
+  return question.recommendedCount ?? question.minSelections;
+}

package/src/questionnaire/index.ts

@@ -0,0 +1,67 @@
+import {
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { askQuestions } from "./helpers.js";
+import type { Question, QuestionnaireResult } from "./types.js";
+import { renderCallText } from "../utils.js";
+import { QuestionnaireParamsSchema } from "./schemas.js";
+
+export function createQuestionnaireTool(parentCtx?: ExtensionContext) {
+  return defineTool({
+    name: "questionnaire",
+    label: "Questionnaire",
+    description:
+      "Ask user focused clarifying question(s) when answer changes next step. Prefer over guessing.",
+    promptSnippet:
+      "Clarify material unknowns with user. Ask 1 question or a small batch before committing.",
+    promptGuidelines: [
+      "Use when answer changes design, safety, scope, or next step.",
+      "If multiple viable approaches remain, ask before choosing.",
+      "If user invites questions, lower threshold.",
+      "Ask 1 focused question or a small related batch.",
+      "Prefer questionnaire over plain-text follow-up when UI is available.",
+      "Do not ask what repo or prior answers already provide.",
+    ],
+    parameters: QuestionnaireParamsSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const interactionCtx = parentCtx ?? ctx;
+      if (!interactionCtx.hasUI) {
+        return {
+          content: [{ type: "text", text: "Questionnaire requires an interactive UI." }],
+          details: { cancelled: true, questions: [], answers: [] } satisfies QuestionnaireResult,
+        };
+      }
+
+      const result = await askQuestions(params.questions, interactionCtx.ui);
+      if (result.cancelled) {
+        return {
+          content: [{ type: "text", text: "User cancelled the questionnaire." }],
+          details: result,
+        };
+      }
+
+      const content = result.questions
+        .map(
+          (question, idx) => `Q${idx + 1}: ${question}\nA${idx + 1}: ${result.answers[idx] ?? ""}`,
+        )
+        .join("\n\n");
+
+      return {
+        content: [{ type: "text", text: content }],
+        details: result,
+      };
+    },
+    renderCall(args, theme, { isPartial }) {
+      const questions = ((args.questions as Question[] | undefined) ?? []).filter(Boolean);
+      const count = questions.length;
+      let text = `${theme.fg("toolTitle", "questionnaire")} ${theme.fg("muted", `${count} question${count === 1 ? "" : "s"}`)}`;
+      return renderCallText(text, isPartial);
+    },
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(createQuestionnaireTool());
+}

package/src/questionnaire/schemas.ts

@@ -0,0 +1,50 @@
+import Type from "typebox";
+
+export const QuestionOptionSchema = Type.Object({
+  text: Type.String({ description: "Option text" }),
+  description: Type.Optional(Type.String({ description: "Option helper text" })),
+  exclusive: Type.Optional(
+    Type.Boolean({
+      description: "If selected, clears other options",
+    }),
+  ),
+});
+
+export const QuestionSchema = Type.Object({
+  prompt: Type.String({ description: "Question text" }),
+  reason: Type.Optional(Type.String({ description: "Why answer matters" })),
+  options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Suggested options" })),
+  placeholder: Type.String({
+    description: "Freeform input placeholder",
+    default: "Type your answer",
+  }),
+  multi: Type.Optional(Type.Boolean({ description: "Allow multiple options" })),
+  recommendedCount: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Recommended options count",
+    }),
+  ),
+  minSelections: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Min options to select (if multi=true)" }),
+  ),
+  maxSelections: Type.Optional(
+    Type.Integer({ minimum: 1, description: "Max options to select (if multi=true)" }),
+  ),
+});
+
+export const QuestionnaireParamsSchema = Type.Object({
+  questions: Type.Array(QuestionSchema, {
+    minItems: 1,
+    description: "Questions to ask",
+  }),
+});
+
+export const QuestionnaireResultSchema = Type.Object({
+  cancelled: Type.Boolean({
+    description: "True if user cancelled questionnaire tool",
+  }),
+  answers: Type.Array(Type.String(), {
+    description: "Final answers in questions order",
+  }),
+});