@dreki-gg/pi-questionnaire 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @dreki-gg/pi-questionnaire
+
+Tool-first questionnaire extension for pi.
+
+It adds:
+- a `questionnaire` tool for collecting **1-5 structured answers** in one interaction
+- a `/questionnaire` demo command powered by the same shared tabbed TUI flow
+
+## Install
+
+```bash
+pi install npm:@dreki-gg/pi-questionnaire
+```
+
+## What it provides
+
+| Feature | Name | Notes |
+|---|---|---|
+| Tool | `questionnaire` | Collects structured user answers with single/multi select + optional Other text |
+| Command | `/questionnaire` | Demo flow using `Scope`, `Priority`, `Approach` |
+
+## Input schema (summary)
+
+```ts
+{
+  questions: Array<{
+    id: string;
+    label?: string;
+    prompt: string;
+    selectionMode?: 'single' | 'multiple';
+    options: Array<{
+      value: string;
+      label: string;
+      description?: string;
+    }>;
+    allowOther?: boolean; // defaults to true at runtime
+  }> // min 1, max 5
+}
+```
+
+Validation includes:
+- 1-5 question limit
+- non-empty option lists
+- duplicate question id rejection
+- duplicate option value rejection per question
+
+## Normalized output schema (summary)
+
+```ts
+{
+  questions: NormalizedQuestion[];
+  answers: Array<{
+    questionId: string;
+    questionLabel: string;
+    selectedOptions: Array<{ value: string; label: string }>;
+    otherText: string | null;
+    wasOtherSelected: boolean;
+  }>;
+  cancelled: boolean;
+}
+```
+
+`Other` answers are rendered explicitly as:
+
+```text
+Other: "GraphQL"
+```
+
+## Keyboard model
+
+- `← / →`: switch tabs (question tabs + Review tab)
+- `↑ / ↓`: move option cursor (question tab) or row cursor (Review tab)
+- `Space`:
+  - question tab: select/toggle option or enter Other input
+  - review tab: jump to selected question for editing
+- `r`: jump to Review tab
+- `Esc` hierarchy:
+  1. exit Other input mode
+  2. from Review, go back to prior question tab
+  3. from question tab outermost, cancel questionnaire
+- `Enter`:
+  - in Other editor: submit typed text
+  - in Review: submit only when all required answers are valid
+
+## Example tool call
+
+```json
+{
+  "name": "questionnaire",
+  "arguments": {
+    "questions": [
+      {
+        "id": "scope",
+        "label": "Scope",
+        "prompt": "What is the project scope?",
+        "selectionMode": "single",
+        "options": [
+          { "value": "low", "label": "Low" },
+          { "value": "high", "label": "High" }
+        ]
+      },
+      {
+        "id": "priority",
+        "label": "Priority",
+        "prompt": "What priority should we assign?",
+        "selectionMode": "single",
+        "options": [
+          { "value": "p0", "label": "P0" },
+          { "value": "p1", "label": "P1" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Example result summaries
+
+Completed (collapsed):
+
+```text
+✓ Scope: High • Priority: P1 • Approach: Other: "GraphQL"
+```
+
+Cancelled:
+
+```text
+⚠ Cancelled
+```
+
+## Cancellation and non-interactive behavior
+
+- User cancellation is **not treated as an error** (`cancelled: true` in details).
+- Non-interactive mode (`!ctx.hasUI`) returns an immediate error result (`isError: true`).

package/extensions/questionnaire/format.ts

@@ -0,0 +1,189 @@
+import type {
+  NormalizedAnswer,
+  NormalizedQuestion,
+  QuestionInput,
+  QuestionSelectionState,
+  QuestionnaireResult,
+  SelectedOption,
+} from './types.js';
+
+export function validateQuestions(
+  questions: QuestionInput[],
+): { valid: true } | { valid: false; error: string } {
+  if (questions.length === 0) {
+    return { valid: false, error: 'Questionnaire must include at least 1 question.' };
+  }
+
+  if (questions.length > 5) {
+    return { valid: false, error: 'Questionnaire supports at most 5 questions.' };
+  }
+
+  const idSet = new Set<string>();
+
+  for (const [index, question] of questions.entries()) {
+    const questionNumber = index + 1;
+    const questionId = question.id.trim();
+
+    if (!questionId) {
+      return { valid: false, error: `Question ${questionNumber} has an empty id.` };
+    }
+
+    if (idSet.has(questionId)) {
+      return { valid: false, error: `Duplicate question id: "${questionId}".` };
+    }
+    idSet.add(questionId);
+
+    if (!question.options.length) {
+      return {
+        valid: false,
+        error: `Question "${questionId}" must include at least one listed option.`,
+      };
+    }
+
+    const valueSet = new Set<string>();
+    for (const option of question.options) {
+      const optionValue = option.value.trim();
+      if (!optionValue) {
+        return {
+          valid: false,
+          error: `Question "${questionId}" has an option with an empty value.`,
+        };
+      }
+      if (valueSet.has(optionValue)) {
+        return {
+          valid: false,
+          error: `Question "${questionId}" has duplicate option value "${optionValue}".`,
+        };
+      }
+      valueSet.add(optionValue);
+    }
+  }
+
+  return { valid: true };
+}
+
+export function normalizeQuestions(questions: QuestionInput[]): NormalizedQuestion[] {
+  return questions.map((question, index) => ({
+    id: question.id.trim(),
+    label: question.label?.trim() || question.id.trim() || `Q${index + 1}`,
+    prompt: question.prompt.trim(),
+    selectionMode: question.selectionMode ?? 'single',
+    options: question.options.map((option) => ({
+      value: option.value.trim(),
+      label: option.label,
+      description: option.description,
+    })),
+    allowOther: question.allowOther !== false,
+  }));
+}
+
+export function createInitialQuestionStateById(
+  questions: NormalizedQuestion[],
+): Record<string, QuestionSelectionState> {
+  return Object.fromEntries(
+    questions.map((question) => [
+      question.id,
+      {
+        listedSelectedValues: [],
+        otherText: '',
+        wasOtherSelected: false,
+      } satisfies QuestionSelectionState,
+    ]),
+  );
+}
+
+function hasValidOtherText(state: QuestionSelectionState): boolean {
+  return state.wasOtherSelected && state.otherText.trim().length > 0;
+}
+
+export function isAnswerValid(
+  question: NormalizedQuestion,
+  state: QuestionSelectionState,
+): boolean {
+  const selectedListedCount = state.listedSelectedValues.length;
+  const hasOtherText = hasValidOtherText(state);
+
+  if (question.selectionMode === 'single') {
+    const hasSingleListed = selectedListedCount === 1 && !state.wasOtherSelected;
+    const hasSingleOther = selectedListedCount === 0 && hasOtherText;
+    return hasSingleListed || hasSingleOther;
+  }
+
+  return selectedListedCount > 0 || hasOtherText;
+}
+
+export function areAllAnswersValid(
+  questions: NormalizedQuestion[],
+  stateById: Record<string, QuestionSelectionState>,
+): boolean {
+  return questions.every((question) => {
+    const state = stateById[question.id];
+    if (!state) return false;
+    return isAnswerValid(question, state);
+  });
+}
+
+export function normalizeAnswer(
+  question: NormalizedQuestion,
+  state: QuestionSelectionState,
+): NormalizedAnswer {
+  const selectedSet = new Set(state.listedSelectedValues);
+  const selectedOptions: SelectedOption[] = question.options
+    .filter((option) => selectedSet.has(option.value))
+    .map((option) => ({ value: option.value, label: option.label }));
+
+  const trimmedOther = state.otherText.trim();
+
+  return {
+    questionId: question.id,
+    questionLabel: question.label,
+    selectedOptions,
+    otherText: state.wasOtherSelected && trimmedOther ? trimmedOther : null,
+    wasOtherSelected: state.wasOtherSelected,
+  };
+}
+
+export function normalizeAnswers(
+  questions: NormalizedQuestion[],
+  stateById: Record<string, QuestionSelectionState>,
+): NormalizedAnswer[] {
+  return questions.map((question) =>
+    normalizeAnswer(question, stateById[question.id] ?? createEmptyQuestionState()),
+  );
+}
+
+function createEmptyQuestionState(): QuestionSelectionState {
+  return { listedSelectedValues: [], otherText: '', wasOtherSelected: false };
+}
+
+export function formatAnswerValue(answer: NormalizedAnswer): string {
+  const listed = answer.selectedOptions.map((option) => option.label).join(', ');
+  const other = answer.otherText ? `Other: "${answer.otherText}"` : '';
+
+  if (listed && other) return `${listed} + ${other}`;
+  if (listed) return listed;
+  if (other) return other;
+  return '—';
+}
+
+export function formatCompletedSummary(result: QuestionnaireResult): string {
+  const parts = result.answers.map(
+    (answer) => `${answer.questionLabel}: ${formatAnswerValue(answer)}`,
+  );
+  return `✓ ${parts.join(' • ')}`;
+}
+
+export function formatCancelledSummary(): string {
+  return '⚠ Cancelled';
+}
+
+export function formatExpandedAnswerLines(result: QuestionnaireResult): string[] {
+  return result.answers.map((answer) => `${answer.questionLabel}: ${formatAnswerValue(answer)}`);
+}
+
+export function formatToolContentSummary(result: QuestionnaireResult): string {
+  if (result.cancelled) {
+    return formatCancelledSummary();
+  }
+  return formatExpandedAnswerLines(result).join('\n');
+}

package/extensions/questionnaire/index.ts

@@ -0,0 +1,205 @@
+import type { ExtensionAPI, Theme } from '@mariozechner/pi-coding-agent';
+import { Container, Spacer, Text } from '@mariozechner/pi-tui';
+import {
+  formatCancelledSummary,
+  formatCompletedSummary,
+  formatExpandedAnswerLines,
+  formatToolContentSummary,
+  normalizeQuestions,
+  validateQuestions,
+} from './format.js';
+import { QuestionnaireParamsSchema } from './schema.js';
+import type { QuestionInput, QuestionnaireResult, SelectionMode, SelectedOption } from './types.js';
+import { runQuestionnaireUI } from './ui.js';
+
+function emptyResult(error?: string): QuestionnaireResult {
+  return {
+    questions: [],
+    answers: [],
+    cancelled: true,
+    ...(error ? { error } : {}),
+  };
+}
+
+function buildErrorResult(error: string, details: QuestionnaireResult = emptyResult(error)) {
+  return {
+    content: [{ type: 'text' as const, text: `Error: ${error}` }],
+    details,
+    isError: true,
+  };
+}
+
+function getCallLabels(questions: QuestionInput[]): string[] {
+  return questions.map((question, index) => {
+    const trimmed = question.label?.trim();
+    if (trimmed) return trimmed;
+    return question.id.trim() || `Q${index + 1}`;
+  });
+}
+
+function renderCollapsedCall(questions: QuestionInput[], theme: Theme): string {
+  const labels = getCallLabels(questions);
+  const count = questions.length;
+  const suffix = count === 1 ? 'question' : 'questions';
+  const labelsText = labels.length ? ` (${labels.join(', ')})` : '';
+
+  return (
+    theme.fg('toolTitle', theme.bold('questionnaire ')) +
+    theme.fg('muted', `${count} ${suffix}`) +
+    theme.fg('dim', labelsText)
+  );
+}
+
+function selectedOption(value: string, label: string): SelectedOption {
+  return { value, label };
+}
+
+function demoQuestions(): QuestionInput[] {
+  return [
+    {
+      id: 'scope',
+      label: 'Scope',
+      prompt: 'What is the project scope?',
+      selectionMode: 'single' satisfies SelectionMode,
+      options: [
+        selectedOption('small', 'Small'),
+        selectedOption('medium', 'Medium'),
+        selectedOption('high', 'High'),
+      ],
+      allowOther: true,
+    },
+    {
+      id: 'priority',
+      label: 'Priority',
+      prompt: 'What priority should we assign?',
+      selectionMode: 'single' satisfies SelectionMode,
+      options: [selectedOption('p0', 'P0'), selectedOption('p1', 'P1'), selectedOption('p2', 'P2')],
+      allowOther: true,
+    },
+    {
+      id: 'approach',
+      label: 'Approach',
+      prompt: 'Which implementation approach do you want?',
+      selectionMode: 'single' satisfies SelectionMode,
+      options: [
+        selectedOption('rest', 'REST API'),
+        selectedOption('event-driven', 'Event-driven'),
+        selectedOption('serverless', 'Serverless'),
+      ],
+      allowOther: true,
+    },
+  ];
+}
+
+export default function questionnaireExtension(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: 'questionnaire',
+    label: 'Questionnaire',
+    description:
+      'Collect 1-5 structured user answers in a single interactive questionnaire flow. Supports single and multi-select prompts with optional Other text.',
+    promptSnippet:
+      'Gather explicit user choices with a structured questionnaire before proceeding with implementation or planning.',
+    promptGuidelines: [
+      'Use this tool when you need explicit user choices before continuing.',
+      'Batch related clarification questions into one questionnaire call instead of many single prompts.',
+      'Only call this tool in interactive sessions with UI available.',
+    ],
+    parameters: QuestionnaireParamsSchema,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const validation = validateQuestions(params.questions);
+      if (!validation.valid) {
+        return buildErrorResult(validation.error);
+      }
+
+      const normalizedQuestions = normalizeQuestions(params.questions);
+
+      if (!ctx.hasUI) {
+        return buildErrorResult('UI not available (running in non-interactive mode).', {
+          questions: normalizedQuestions,
+          answers: [],
+          cancelled: true,
+          error: 'UI not available (running in non-interactive mode).',
+        });
+      }
+
+      const uiResult = await runQuestionnaireUI(ctx, normalizedQuestions);
+
+      if (uiResult.cancelled) {
+        return {
+          content: [{ type: 'text' as const, text: formatCancelledSummary() }],
+          details: uiResult,
+          isError: false,
+          cancelled: true,
+        };
+      }
+
+      return {
+        content: [{ type: 'text' as const, text: formatToolContentSummary(uiResult) }],
+        details: uiResult,
+      };
+    },
+
+    renderCall(args, theme, _context) {
+      return new Text(renderCollapsedCall(args.questions, theme), 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme, _context) {
+      const details = result.details as QuestionnaireResult | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === 'text' ? text.text : '', 0, 0);
+      }
+
+      if (details.error) {
+        return new Text(theme.fg('error', `Error: ${details.error}`), 0, 0);
+      }
+
+      if (details.cancelled) {
+        if (!expanded) {
+          return new Text(theme.fg('warning', formatCancelledSummary()), 0, 0);
+        }
+
+        const container = new Container();
+        container.addChild(new Text(theme.fg('warning', formatCancelledSummary()), 0, 0));
+        container.addChild(new Spacer(1));
+        container.addChild(new Text(theme.fg('muted', 'No submission occurred.'), 0, 0));
+        return container;
+      }
+
+      if (!expanded) {
+        return new Text(theme.fg('success', formatCompletedSummary(details)), 0, 0);
+      }
+
+      const container = new Container();
+      container.addChild(new Text(theme.fg('success', formatCompletedSummary(details)), 0, 0));
+      container.addChild(new Spacer(1));
+
+      for (const line of formatExpandedAnswerLines(details)) {
+        container.addChild(new Text(theme.fg('text', line), 0, 0));
+      }
+
+      return container;
+    },
+  });
+
+  pi.registerCommand('questionnaire', {
+    description: 'Run a demo questionnaire flow.',
+    handler: async (_args, ctx) => {
+      const questions = normalizeQuestions(demoQuestions());
+
+      if (!ctx.hasUI) {
+        ctx.ui.notify('/questionnaire requires interactive mode.', 'error');
+        return;
+      }
+
+      const result = await runQuestionnaireUI(ctx, questions);
+      if (result.cancelled) {
+        ctx.ui.notify(formatCancelledSummary(), 'warning');
+        return;
+      }
+
+      ctx.ui.notify(formatCompletedSummary(result), 'info');
+    },
+  });
+}

package/extensions/questionnaire/schema.ts

@@ -0,0 +1,46 @@
+import { StringEnum } from '@mariozechner/pi-ai';
+import { Type, type Static } from '@sinclair/typebox';
+
+export const SelectionModeSchema = StringEnum(['single', 'multiple'] as const, {
+  description: 'Selection mode: single choice or multiple choices.',
+  default: 'single',
+});
+
+export const QuestionOptionSchema = Type.Object({
+  value: Type.String({ description: 'Stable value returned when this option is selected.' }),
+  label: Type.String({ description: 'User-facing label for this option.' }),
+  description: Type.Optional(
+    Type.String({ description: 'Optional helper text displayed under the label.' }),
+  ),
+});
+
+export const QuestionSchema = Type.Object({
+  id: Type.String({ description: 'Unique question identifier.' }),
+  label: Type.Optional(
+    Type.String({ description: 'Short label shown in tabs and summaries (defaults to id).' }),
+  ),
+  prompt: Type.String({ description: 'Full prompt shown for this question.' }),
+  selectionMode: Type.Optional(SelectionModeSchema),
+  options: Type.Array(QuestionOptionSchema, {
+    minItems: 1,
+    description: 'Options available to the user.',
+  }),
+  allowOther: Type.Optional(
+    Type.Boolean({
+      description: 'Whether the question includes an Other free-text option (default true).',
+    }),
+  ),
+});
+
+export const QuestionnaireParamsSchema = Type.Object({
+  questions: Type.Array(QuestionSchema, {
+    minItems: 1,
+    maxItems: 5,
+    description: 'Question list. Must contain between 1 and 5 questions.',
+  }),
+});
+
+export type SelectionMode = Static<typeof SelectionModeSchema>;
+export type QuestionOption = Static<typeof QuestionOptionSchema>;
+export type QuestionInput = Static<typeof QuestionSchema>;
+export type QuestionnaireParams = Static<typeof QuestionnaireParamsSchema>;

package/extensions/questionnaire/types.ts

@@ -0,0 +1,67 @@
+import { StringEnum } from '@mariozechner/pi-ai';
+import { Type, type Static } from '@sinclair/typebox';
+import {
+  type QuestionInput as QuestionInputSchema,
+  type QuestionOption as QuestionOptionSchema,
+  type SelectionMode as SelectionModeSchema,
+} from './schema.js';
+
+export type QuestionOption = QuestionOptionSchema;
+export type QuestionInput = QuestionInputSchema;
+export type SelectionMode = SelectionModeSchema;
+
+export interface NormalizedQuestion {
+  id: string;
+  label: string;
+  prompt: string;
+  selectionMode: SelectionMode;
+  options: QuestionOption[];
+  allowOther: boolean;
+}
+
+export const SelectedOptionSchema = Type.Object({
+  value: Type.String(),
+  label: Type.String(),
+});
+
+export type SelectedOption = Static<typeof SelectedOptionSchema>;
+
+export interface NormalizedAnswer {
+  questionId: string;
+  questionLabel: string;
+  selectedOptions: SelectedOption[];
+  otherText: string | null;
+  wasOtherSelected: boolean;
+}
+
+export interface QuestionnaireResult {
+  questions: NormalizedQuestion[];
+  answers: NormalizedAnswer[];
+  cancelled: boolean;
+  error?: string;
+}
+
+export interface QuestionSelectionState {
+  listedSelectedValues: string[];
+  otherText: string;
+  wasOtherSelected: boolean;
+}
+
+export const QuestionnaireInputModeSchema = StringEnum(['navigate', 'otherInput'] as const, {
+  description: 'Current input mode for questionnaire UI state.',
+  default: 'navigate',
+});
+
+export type QuestionnaireInputMode = Static<typeof QuestionnaireInputModeSchema>;
+
+export interface QuestionnaireUIState {
+  activeTabIndex: number;
+  lastQuestionTabIndex: number;
+  questionOptionCursorById: Record<string, number>;
+  reviewCursor: number;
+  inputMode: QuestionnaireInputMode;
+  editingQuestionId?: string;
+  returnToReview: boolean;
+  returnReviewCursor: number;
+  questionStateById: Record<string, QuestionSelectionState>;
+}

package/extensions/questionnaire/ui.ts

@@ -0,0 +1,487 @@
+import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import {
+  areAllAnswersValid,
+  createInitialQuestionStateById,
+  formatAnswerValue,
+  isAnswerValid,
+  normalizeAnswers,
+} from './format.js';
+import type {
+  NormalizedQuestion,
+  QuestionSelectionState,
+  QuestionnaireResult,
+  QuestionnaireUIState,
+} from './types.js';
+
+interface RenderOption {
+  kind: 'listed' | 'other';
+  value: string;
+  label: string;
+  description?: string;
+}
+
+const REVIEW_LABEL_READY = ' ✓ Review ';
+const REVIEW_LABEL_PENDING = ' □ Review ';
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function isSpaceKey(data: string): boolean {
+  return data === ' ' || matchesKey(data, Key.space);
+}
+
+function isRKey(data: string): boolean {
+  return data === 'r' || data === 'R' || matchesKey(data, 'r');
+}
+
+function getRenderOptions(question: NormalizedQuestion): RenderOption[] {
+  const listed: RenderOption[] = question.options.map((option) => ({
+    kind: 'listed',
+    value: option.value,
+    label: option.label,
+    description: option.description,
+  }));
+
+  if (!question.allowOther) return listed;
+
+  listed.push({ kind: 'other', value: '__other__', label: 'Other' });
+  return listed;
+}
+
+function ensureQuestionState(
+  stateById: Record<string, QuestionSelectionState>,
+  questionId: string,
+): QuestionSelectionState {
+  stateById[questionId] ??= { listedSelectedValues: [], otherText: '', wasOtherSelected: false };
+  return stateById[questionId];
+}
+
+export async function runQuestionnaireUI(
+  ctx: Pick<ExtensionContext, 'ui'>,
+  questions: NormalizedQuestion[],
+): Promise<QuestionnaireResult> {
+  const reviewTabIndex = questions.length;
+
+  return ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {
+    const uiState: QuestionnaireUIState = {
+      activeTabIndex: 0,
+      lastQuestionTabIndex: 0,
+      questionOptionCursorById: Object.fromEntries(questions.map((question) => [question.id, 0])),
+      reviewCursor: 0,
+      inputMode: 'navigate',
+      editingQuestionId: undefined,
+      returnToReview: false,
+      returnReviewCursor: 0,
+      questionStateById: createInitialQuestionStateById(questions),
+    };
+
+    const editorTheme: EditorTheme = {
+      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),
+      },
+    };
+
+    const editor = new Editor(tui, editorTheme);
+
+    let cachedWidth: number | undefined;
+    let cachedLines: string[] | undefined;
+
+    editor.onSubmit = (value) => {
+      if (!uiState.editingQuestionId) return;
+      const selection = ensureQuestionState(uiState.questionStateById, uiState.editingQuestionId);
+      selection.wasOtherSelected = true;
+      selection.otherText = value.trim();
+      uiState.inputMode = 'navigate';
+      uiState.editingQuestionId = undefined;
+      invalidate();
+    };
+
+    function invalidate() {
+      cachedWidth = undefined;
+      cachedLines = undefined;
+      tui.requestRender();
+    }
+
+    function finalize(cancelled: boolean) {
+      done({
+        questions,
+        answers: normalizeAnswers(questions, uiState.questionStateById),
+        cancelled,
+      });
+    }
+
+    function clearInputMode() {
+      uiState.inputMode = 'navigate';
+      uiState.editingQuestionId = undefined;
+    }
+
+    function getActiveQuestion(): NormalizedQuestion | undefined {
+      if (uiState.activeTabIndex >= questions.length) return undefined;
+      return questions[uiState.activeTabIndex];
+    }
+
+    function switchTabs(delta: number) {
+      if (questions.length === 0) return;
+      const totalTabs = questions.length + 1;
+      const nextTab = (uiState.activeTabIndex + delta + totalTabs) % totalTabs;
+
+      if (uiState.activeTabIndex < questions.length) {
+        uiState.lastQuestionTabIndex = uiState.activeTabIndex;
+      }
+
+      clearInputMode();
+
+      if (nextTab < questions.length) {
+        uiState.lastQuestionTabIndex = nextTab;
+      }
+
+      uiState.activeTabIndex = nextTab;
+      invalidate();
+    }
+
+    function jumpToReview() {
+      if (uiState.activeTabIndex < questions.length) {
+        uiState.lastQuestionTabIndex = uiState.activeTabIndex;
+      }
+
+      if (uiState.returnToReview) {
+        uiState.reviewCursor = clamp(
+          uiState.returnReviewCursor,
+          0,
+          Math.max(0, questions.length - 1),
+        );
+      }
+
+      uiState.returnToReview = false;
+      uiState.activeTabIndex = reviewTabIndex;
+      clearInputMode();
+      invalidate();
+    }
+
+    function handleQuestionSelection(question: NormalizedQuestion, option: RenderOption) {
+      const selection = ensureQuestionState(uiState.questionStateById, question.id);
+
+      if (option.kind === 'other') {
+        if (question.selectionMode === 'single') {
+          selection.listedSelectedValues = [];
+        }
+        selection.wasOtherSelected = true;
+        uiState.inputMode = 'otherInput';
+        uiState.editingQuestionId = question.id;
+        editor.setText(selection.otherText);
+        invalidate();
+        return;
+      }
+
+      if (question.selectionMode === 'single') {
+        selection.listedSelectedValues = [option.value];
+        selection.wasOtherSelected = false;
+        selection.otherText = '';
+      } else {
+        const existing = new Set(selection.listedSelectedValues);
+        if (existing.has(option.value)) existing.delete(option.value);
+        else existing.add(option.value);
+        selection.listedSelectedValues = question.options
+          .map((item) => item.value)
+          .filter((value) => existing.has(value));
+      }
+
+      invalidate();
+    }
+
+    function jumpFromReviewToQuestion() {
+      const targetIndex = clamp(uiState.reviewCursor, 0, Math.max(0, questions.length - 1));
+      uiState.returnReviewCursor = targetIndex;
+      uiState.returnToReview = true;
+      uiState.activeTabIndex = targetIndex;
+      uiState.lastQuestionTabIndex = targetIndex;
+      clearInputMode();
+      invalidate();
+    }
+
+    function moveQuestionCursor(delta: number) {
+      const question = getActiveQuestion();
+      if (!question) return;
+      const options = getRenderOptions(question);
+      if (options.length === 0) return;
+      const currentCursor = uiState.questionOptionCursorById[question.id] ?? 0;
+      uiState.questionOptionCursorById[question.id] = clamp(
+        currentCursor + delta,
+        0,
+        options.length - 1,
+      );
+      invalidate();
+    }
+
+    function handleInput(data: string) {
+      if (uiState.inputMode === 'otherInput' && matchesKey(data, Key.escape)) {
+        clearInputMode();
+        invalidate();
+        return;
+      }
+
+      if (matchesKey(data, Key.left)) {
+        switchTabs(-1);
+        return;
+      }
+
+      if (matchesKey(data, Key.right)) {
+        switchTabs(1);
+        return;
+      }
+
+      if (isRKey(data)) {
+        jumpToReview();
+        return;
+      }
+
+      if (uiState.inputMode === 'otherInput') {
+        editor.handleInput(data);
+        invalidate();
+        return;
+      }
+
+      if (uiState.activeTabIndex === reviewTabIndex) {
+        if (matchesKey(data, Key.up)) {
+          uiState.reviewCursor = clamp(
+            uiState.reviewCursor - 1,
+            0,
+            Math.max(0, questions.length - 1),
+          );
+          invalidate();
+          return;
+        }
+
+        if (matchesKey(data, Key.down)) {
+          uiState.reviewCursor = clamp(
+            uiState.reviewCursor + 1,
+            0,
+            Math.max(0, questions.length - 1),
+          );
+          invalidate();
+          return;
+        }
+
+        if (isSpaceKey(data)) {
+          jumpFromReviewToQuestion();
+          return;
+        }
+
+        if (matchesKey(data, Key.enter)) {
+          if (areAllAnswersValid(questions, uiState.questionStateById)) {
+            finalize(false);
+          }
+          return;
+        }
+
+        if (matchesKey(data, Key.escape)) {
+          uiState.activeTabIndex = clamp(
+            uiState.lastQuestionTabIndex,
+            0,
+            Math.max(0, questions.length - 1),
+          );
+          uiState.returnToReview = false;
+          invalidate();
+        }
+
+        return;
+      }
+
+      const question = getActiveQuestion();
+      if (!question) return;
+
+      if (matchesKey(data, Key.up)) {
+        moveQuestionCursor(-1);
+        return;
+      }
+
+      if (matchesKey(data, Key.down)) {
+        moveQuestionCursor(1);
+        return;
+      }
+
+      if (isSpaceKey(data)) {
+        const options = getRenderOptions(question);
+        const cursor = clamp(
+          uiState.questionOptionCursorById[question.id] ?? 0,
+          0,
+          options.length - 1,
+        );
+        const option = options[cursor];
+        if (!option) return;
+        handleQuestionSelection(question, option);
+        return;
+      }
+
+      if (matchesKey(data, Key.escape)) {
+        finalize(true);
+      }
+    }
+
+    function renderTabs(width: number, lines: string[]) {
+      const allValid = areAllAnswersValid(questions, uiState.questionStateById);
+      const renderedTabs = questions.map((question, index) => {
+        const state = ensureQuestionState(uiState.questionStateById, question.id);
+        const answered = isAnswerValid(question, state);
+        const marker = answered ? '■' : '□';
+        const text = ` ${marker} ${question.label} `;
+        if (uiState.activeTabIndex === index) {
+          return theme.bg('selectedBg', theme.fg('text', text));
+        }
+        return theme.fg(answered ? 'success' : 'muted', text);
+      });
+
+      const reviewText = allValid ? REVIEW_LABEL_READY : REVIEW_LABEL_PENDING;
+      const reviewStyled =
+        uiState.activeTabIndex === reviewTabIndex
+          ? theme.bg('selectedBg', theme.fg('text', reviewText))
+          : theme.fg(allValid ? 'success' : 'muted', reviewText);
+
+      const tabLine = renderedTabs.concat(reviewStyled).join(' ');
+      lines.push(truncateToWidth(tabLine, width));
+      lines.push('');
+    }
+
+    function renderQuestionBody(width: number, lines: string[], question: NormalizedQuestion) {
+      const selection = ensureQuestionState(uiState.questionStateById, question.id);
+      const options = getRenderOptions(question);
+      const cursor = clamp(
+        uiState.questionOptionCursorById[question.id] ?? 0,
+        0,
+        options.length - 1,
+      );
+
+      lines.push(truncateToWidth(theme.fg('text', question.prompt), width));
+      lines.push('');
+
+      for (const [index, option] of options.entries()) {
+        const isCursor = cursor === index;
+        const prefix = isCursor ? theme.fg('accent', '> ') : '  ';
+
+        if (option.kind === 'other') {
+          const activeOtherText = selection.otherText.trim();
+          const label = activeOtherText
+            ? `Other: "${activeOtherText}"`
+            : selection.wasOtherSelected
+              ? 'Other (empty)'
+              : 'Other';
+          const marker = selection.wasOtherSelected ? '[x]' : '[ ]';
+          const color = selection.wasOtherSelected ? 'accent' : 'text';
+          lines.push(truncateToWidth(`${prefix}${theme.fg(color, `${marker} ${label}`)}`, width));
+          continue;
+        }
+
+        const selected = selection.listedSelectedValues.includes(option.value);
+        const marker = selected ? '[x]' : '[ ]';
+        const color = selected ? 'accent' : 'text';
+        lines.push(
+          truncateToWidth(`${prefix}${theme.fg(color, `${marker} ${option.label}`)}`, width),
+        );
+
+        if (option.description) {
+          lines.push(truncateToWidth(`    ${theme.fg('muted', option.description)}`, width));
+        }
+      }
+
+      if (uiState.inputMode === 'otherInput' && uiState.editingQuestionId === question.id) {
+        lines.push('');
+        lines.push(truncateToWidth(theme.fg('muted', 'Other input:'), width));
+        for (const line of editor.render(Math.max(10, width - 2))) {
+          lines.push(truncateToWidth(` ${line}`, width));
+        }
+      }
+    }
+
+    function renderReviewBody(width: number, lines: string[]) {
+      const ready = areAllAnswersValid(questions, uiState.questionStateById);
+      const normalizedAnswers = normalizeAnswers(questions, uiState.questionStateById);
+
+      lines.push(truncateToWidth(theme.fg('accent', theme.bold('Review answers')), width));
+      lines.push('');
+
+      for (const [index, question] of questions.entries()) {
+        const answer = normalizedAnswers[index];
+        const valid = isAnswerValid(
+          question,
+          ensureQuestionState(uiState.questionStateById, question.id),
+        );
+        const cursor = uiState.reviewCursor === index ? theme.fg('accent', '> ') : '  ';
+        const marker = valid ? theme.fg('success', '■') : theme.fg('warning', '□');
+        const value = formatAnswerValue(answer);
+        const color = valid ? 'text' : 'muted';
+        lines.push(
+          truncateToWidth(
+            `${cursor}${marker} ${theme.fg('accent', `${question.label}:`)} ${theme.fg(color, value)}`,
+            width,
+          ),
+        );
+      }
+
+      lines.push('');
+      lines.push(
+        truncateToWidth(
+          ready
+            ? theme.fg('success', 'Press Enter to submit')
+            : theme.fg('warning', 'Complete all questions before submitting.'),
+          width,
+        ),
+      );
+    }
+
+    function renderHint(width: number, lines: string[]) {
+      let hint = '';
+
+      if (uiState.inputMode === 'otherInput') {
+        hint = 'Enter submits Other text • Esc exits input mode';
+      } else if (uiState.activeTabIndex === reviewTabIndex) {
+        hint = '←→ tabs • ↑↓ review row • Space edit • Enter submit • Esc back';
+      } else if (uiState.returnToReview) {
+        hint = 'Editing from Review • press r to return';
+      } else {
+        hint = '←→ tabs • ↑↓ options • Space select/edit • r review • Esc cancel';
+      }
+
+      lines.push('');
+      lines.push(truncateToWidth(theme.fg('dim', hint), width));
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines && cachedWidth === width) {
+        return cachedLines;
+      }
+
+      const lines: string[] = [];
+
+      renderTabs(width, lines);
+
+      const activeQuestion = getActiveQuestion();
+      if (activeQuestion) {
+        renderQuestionBody(width, lines, activeQuestion);
+      } else {
+        renderReviewBody(width, lines);
+      }
+
+      renderHint(width, lines);
+
+      cachedWidth = width;
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      handleInput,
+      invalidate: () => {
+        cachedWidth = undefined;
+        cachedLines = undefined;
+      },
+    };
+  });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dreki-gg/pi-questionnaire",
+  "version": "0.1.0",
+  "description": "Tool-first questionnaire flow for pi with shared tabbed TUI and custom rendering",
+  "keywords": [
+    "pi-package"
+  ],
+  "author": "Juan Albarran <jalbarrandev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreki-gg/pi-extensions",
+    "directory": "packages/questionnaire"
+  },
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint extensions",
+    "format": "oxfmt --write extensions",
+    "format:check": "oxfmt --check extensions"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/questionnaire"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "24",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./node_modules/.cache/questionnaire.tsbuildinfo",
+    "rootDir": "."
+  },
+  "include": ["extensions/**/*.ts"]
+}