pi-ask-questions 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- `ask_user` tool with tabbed questionnaires, single-select and multi-select options, free-form typing, and multiple typed answers per question.
+- Validated answers: required questions, `min`/`max` selection counts, optional questions that can be skipped, and preselected defaults.
+- Review tab that summarizes all answers and allows jumping back to edit any question.
+- Safe cancellation (Esc twice or Ctrl+C) and abort-signal support.
+- Scrollable, width-aware rendering with option descriptions, placeholders, and status icons.
+- Structured tool output (`structuredContent`) alongside a compact model-facing summary.
+- RPC dialog fallback for modes without custom components, and a plain-text fallback for non-interactive modes.
+- `/ask-demo` command to preview the questionnaire UI.
+- Unit and interaction tests covering normalization, validation, formatting, rendering, and keyboard flows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thgilciffart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# pi-ask-questions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interactive questionnaires for [Pi](https://pi.dev): the model runs an `ask_user` tool and you answer in a proper terminal UI — tabs, multi-select, free-form typing, validation, and a review step.
+
+[![npm](https://img.shields.io/npm/v/pi-ask-questions.svg)](https://www.npmjs.com/package/pi-ask-questions)
+[![ci](https://github.com/thgilciffart/pi-ask-questions/actions/workflows/ci.yml/badge.svg)](https://github.com/thgilciffart/pi-ask-questions/actions/workflows/ci.yml)
+
+```text
+────────────────────────────────────────────────────────────
+ ask_user demo
+ ✓ Scope  ◐ Release  · Notes  Submit
+────────────────────────────────────────────────────────────
+ Which parts of the project should this change touch?
+ Select one or more • Space toggles
+
+ ❯ [x] 1. Extension host
+       Tool registration and lifecycle code
+   [ ] 2. TUI component
+       The interactive questionnaire renderer
+   [ ] 3. Documentation
+   [x] 4. Tests
+   ✎ Type something…
+
+ ↑↓ move • Space toggle • A all • C clear • 1-9 jump • Enter confirm
+────────────────────────────────────────────────────────────
+```
+
+## Install
+
+```bash
+pi install npm:pi-ask-questions
+```
+
+Try it for a single invocation without changing your settings:
+
+```bash
+pi -e npm:pi-ask-questions
+```
+
+Once installed, run `/ask-demo` to preview the UI, or just let the model call `ask_user` when it needs input.
+
+## Features
+
+- **Tabs** — every question gets a tab with live status (`○` unanswered, `◐` partially answered, `✓` answered, `·` skipped). Move with `Tab` / `Shift+Tab` or `←` / `→`.
+- **Single-select** radio options with optional descriptions.
+- **Multi-select** checkboxes (`multiple: true`), including `min` / `max` validation, `A` to select all, and `C` to clear.
+- **Free-form typing** — a question without options is a plain text prompt. Typed answers are supported on option questions too via the built-in “Type something…” entry, and multiple-choice questions can collect several typed answers.
+- **Multiple answers** — return any number of selections and typed entries per question.
+- **Optional questions** (`required: false`) that can be skipped, plus preset answers (`selected: true`) and defaults.
+- **Review tab** — see everything before submitting; jump back to any question to edit it.
+- **Validation** — required answers and `min`/`max` selection counts are enforced before submit.
+- **Safe cancel** — `Esc` arms cancellation, a second `Esc` or `Ctrl+C` cancels immediately.
+- **Scrollable option lists** — long lists show `↑ n more` / `↓ n more` indicators.
+- **Structured results** — the tool returns text for the model and a machine-readable `structuredContent` payload for codemode scripts.
+
+## How the model uses it
+
+`ask_user` accepts one or more questions. A single-select question resolves immediately; everything else flows into tabs and a submit step.
+
+```json
+{
+  "title": "Release planning",
+  "questions": [
+    {
+      "id": "scope",
+      "label": "Scope",
+      "question": "Which packages should the release include?",
+      "multiple": true,
+      "min": 1,
+      "options": [
+        { "value": "core", "label": "Core", "description": "Shared runtime code", "selected": true },
+        { "value": "cli", "label": "CLI" },
+        { "value": "docs", "label": "Docs" }
+      ]
+    },
+    {
+      "id": "version",
+      "label": "Version",
+      "question": "How should we version it?",
+      "options": [
+        { "value": "patch", "label": "Patch" },
+        { "value": "minor", "label": "Minor" },
+        { "value": "major", "label": "Major" }
+      ]
+    },
+    {
+      "id": "notes",
+      "label": "Notes",
+      "question": "Anything else I should know?",
+      "required": false,
+      "placeholder": "Type a note, or leave empty…"
+    }
+  ]
+}
+```
+
+The model receives a compact summary such as:
+
+```text
+User answered:
+Scope: selected "Core", "CLI", typed "shared types"
+Version: selected "Minor"
+Notes: (skipped)
+```
+
+### Parameters
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `title` | string | Optional title shown above the questionnaire. |
+| `submitLabel` | string | Label of the submit entry. Default `Submit`. |
+| `questions` | array | 1–12 questions, each rendered as a tab. |
+| `questions[].id` | string | Stable id used in the result. Defaults to `q1`, `q2`, … |
+| `questions[].label` | string | Short tab label. Defaults to `Q1`, `Q2`, … |
+| `questions[].question` | string | The question text. |
+| `questions[].header` | string | Optional context shown under the question. |
+| `questions[].options` | array | Choices. Omit or leave empty for free-form text. |
+| `questions[].options[].value` | string | Value returned when picked. Defaults to the label. |
+| `questions[].options[].label` | string | Display label. |
+| `questions[].options[].description` | string | Explanation shown below the label. |
+| `questions[].options[].selected` | boolean | Preselect the option. |
+| `questions[].multiple` | boolean | Allow more than one selection. |
+| `questions[].allowOther` | boolean | Show the typed-answer entry. Default `true`. |
+| `questions[].required` | boolean | Require an answer before submit. Default `true`. |
+| `questions[].min` / `max` | integer | Selection bounds for multi-select. |
+| `questions[].placeholder` | string | Placeholder for the free-form editor. |
+| `questions[].otherLabel` | string | Custom label for the typed-answer entry. |
+
+### Keyboard reference
+
+| Keys | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab`, `←` / `→` | Switch tabs |
+| `↑` / `↓`, `Home` / `End` | Move the option cursor |
+| `Space` | Toggle a checkbox / select a radio option |
+| `1`–`9` | Jump to an option (toggles it in multi-select) |
+| `A` / `C` | Select all / clear (multi-select) |
+| `Enter` | Confirm the question, open the editor, or submit |
+| `Esc` | Leave the editor, arm cancel; `Esc` twice cancels |
+| `Ctrl+C` | Cancel immediately |
+| `\` + `Enter` | Newline in the free-form editor |
+
+## Modes
+
+| Mode | Behavior |
+| --- | --- |
+| Interactive TUI | Full tabbed questionnaire. |
+| RPC | Sequential fallback built from the dialog API (`select` / `input`). |
+| Print / JSON | The tool reports that no UI is available and lists the questions so the model can ask them in plain text. |
+
+## Development
+
+```bash
+npm install
+npm run check          # typecheck + unit tests
+pi -e ./src/extension.ts
+```
+
+The pure questionnaire model (`src/questions.ts`), the TUI component (`src/ui/ask-questionnaire.ts`), and the extension wiring are covered by unit and interaction tests that drive the component with raw key sequences.
+
+## Publishing
+
+The package is published to npm as `pi-ask-questions` and carries the `pi-package` keyword, which makes it eligible for the [Pi package gallery](https://pi.dev/packages). `prepublishOnly` runs the full check suite.
+
+```bash
+npm login
+npm publish
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "pi-ask-questions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-ask-questions",
+	"version": "0.1.0",
+	"description": "Interactive questionnaires for Pi: tabs, multi-select, free-form typing, validation, and structured answers.",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-coding-agent",
+		"extension",
+		"questions",
+		"questionnaire",
+		"ask",
+		"multi-select",
+		"tui"
+	],
+	"license": "MIT",
+	"author": "thgilciffart <73938431+thgilciffart@users.noreply.github.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/thgilciffart/pi-ask-questions.git"
+	},
+	"homepage": "https://github.com/thgilciffart/pi-ask-questions#readme",
+	"bugs": {
+		"url": "https://github.com/thgilciffart/pi-ask-questions/issues"
+	},
+	"type": "module",
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/extension.ts"
+		]
+	},
+	"scripts": {
+		"test": "node --test \"test/**/*.test.ts\"",
+		"typecheck": "tsc --noEmit",
+		"check": "npm run typecheck && npm test",
+		"prepublishOnly": "npm run check"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^1.2.0",
+		"@earendil-works/pi-tui": "^1.2.0",
+		"@types/node": "^26.6.5",
+		"typebox": "^1.3.37",
+		"typescript": "^7.0.2"
+	}
+}

package/src/extension.ts

@@ -0,0 +1,271 @@
+/**
+ * pi-ask-questions
+ *
+ * Registers the `ask_user` tool: an interactive questionnaire with tabs,
+ * single- and multi-select options, free-form typing, validation, and
+ * structured answers. Also adds `/ask-demo` so the UI can be previewed
+ * without involving the model.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { runFallbackSurvey } from "./fallback.ts";
+import {
+	type AskResult,
+	type NormalizedQuestion,
+	type QuestionAnswer,
+	DEFAULT_SUBMIT_LABEL,
+	formatAnswersText,
+	normalizeQuestions,
+	toStructuredOutput,
+} from "./questions.ts";
+import {
+	AskUserOutputSchema,
+	AskUserParamsSchema,
+	type AskUserParams,
+} from "./schema.ts";
+import { runQuestionnaire, type QuestionnaireContext } from "./ui/ask-questionnaire.ts";
+/** Structured details stored with the tool result for rendering. */
+export interface AskToolDetails {
+	cancelled: boolean;
+	answers: QuestionAnswer[];
+	questions: NormalizedQuestion[];
+}
+
+const TOOL_DESCRIPTION = `Ask the user one or more questions and wait for their answers. Use it when you need a decision, preference, or piece of information that only the user can provide.
+
+The interactive UI supports:
+- Tabs: every question gets its own tab (Tab / Shift+Tab and arrow keys switch).
+- Single-select and multi-select questions (set multiple: true).
+- Free-form typing: the user can always type a custom answer unless allowOther is false; a question with no options is purely free-form.
+- Optional questions (required: false) that can be skipped, preselected options (selected: true), and min/max selection counts.
+- Number keys 1-9 jump to options; A selects all; C clears a multi-select.
+
+Guidelines:
+- Prefer this tool over asking questions in prose when you actually need the answer to proceed.
+- Group related questions into one call (2-6 questions) instead of asking repeatedly.
+- Provide concrete, labeled options whenever you can; use a free-form question only when the answer space is open.
+- Put recommended options first.`;
+
+const HELP_TEXT = `Interactive UI is not available in this mode. Ask the user the following questions directly in your reply instead:
+{{questions}}`;
+
+/** Dispatch to the right UI for the current mode. */
+async function askQuestions(
+	ctx: Pick<ExtensionContext, "ui" | "mode" | "hasUI">,
+	questions: NormalizedQuestion[],
+	options: { title?: string; submitLabel: string; signal?: AbortSignal },
+): Promise<AskResult> {
+	if (ctx.mode === "tui") {
+		return runQuestionnaire(ctx as QuestionnaireContext, questions, options);
+	}
+	if (ctx.hasUI) {
+		return runFallbackSurvey(ctx.ui, questions, options.signal);
+	}
+	throw new Error("no-ui");
+}
+
+/** Human-readable list used when no UI exists (print/JSON mode). */
+function questionsAsText(questions: NormalizedQuestion[]): string {
+	return questions
+		.map((question, index) => {
+			const options =
+				question.options.length > 0
+					? `\n   Options: ${question.options.map((option) => option.label).join(", ")}`
+					: "";
+			const optional = question.required ? "" : " (optional)";
+			return `${index + 1}. ${question.question}${optional}${options}`;
+		})
+		.join("\n");
+}
+
+function resultContent(result: AskResult): string {
+	if (result.cancelled) {
+		return "The user cancelled the questionnaire before submitting.";
+	}
+	return `User answered:\n${formatAnswersText(result)}`;
+}
+
+/** Start the questionnaire and wait for the user. */
+export default function askQuestionsExtension(pi: ExtensionAPI): void {
+	pi.registerTool<typeof AskUserParamsSchema, AskToolDetails>({
+		name: "ask_user",
+		label: "Ask User",
+		description: TOOL_DESCRIPTION,
+		promptSnippet:
+			"ask_user: ask the user structured questions in an interactive questionnaire (tabs, multi-select, free-form).",
+		promptGuidelines: [
+			"Use ask_user when you need a decision or missing detail from the user; batch related questions into one call instead of asking repeatedly.",
+			"Give ask_user questions labeled options where possible, keep them self-contained, and put recommended options first.",
+		],
+		parameters: AskUserParamsSchema,
+		outputSchema: AskUserOutputSchema,
+		executionMode: "sequential",
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false,
+		},
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const questions = normalizeQuestions(params);
+			if (questions.length === 0) {
+				return {
+					content: [{ type: "text", text: "No questions were provided." }],
+					details: { cancelled: true, answers: [], questions },
+					isError: true,
+				};
+			}
+
+			const submitLabel = params.submitLabel?.trim() || DEFAULT_SUBMIT_LABEL;
+			let result: AskResult;
+			try {
+				result = await askQuestions(ctx, questions, {
+					title: params.title?.trim() || undefined,
+					submitLabel,
+					signal: signal ?? undefined,
+				});
+			} catch (error) {
+				if (error instanceof Error && error.message === "no-ui") {
+					const text = HELP_TEXT.replace("{{questions}}", questionsAsText(questions));
+					return {
+						content: [{ type: "text", text }],
+						details: { cancelled: true, answers: [], questions },
+						isError: true,
+					};
+				}
+				throw error;
+			}
+
+			return {
+				content: [{ type: "text", text: resultContent(result) }],
+				details: {
+					cancelled: result.cancelled,
+					answers: result.answers,
+					questions,
+				},
+				structuredContent: toStructuredOutput(result),
+			};
+		},
+
+		renderCall(args, theme, _context) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const count = questions.length;
+			let text =
+				theme.fg("toolTitle", theme.bold("ask_user ")) +
+				theme.fg("muted", `${count} question${count === 1 ? "" : "s"}`);
+			const labels = questions
+				.map((question, index) => question.label?.trim() || question.id?.trim() || `Q${index + 1}`)
+				.join(", ");
+			if (labels.length > 0) {
+				text += theme.fg("dim", ` (${labels})`);
+			}
+			const first = questions[0]?.question;
+			if (typeof first === "string" && first.length > 0) {
+				text += `\n${theme.fg("dim", `  ${first}`)}`;
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme, _context) {
+			const details = result.details;
+			if (!details) {
+				const content = result.content[0];
+				return new Text(content?.type === "text" ? content.text : "", 0, 0);
+			}
+			if (details.cancelled) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const lines = details.answers.map((answer) => {
+				const label = theme.fg("accent", answer.label);
+				if (answer.skipped) {
+					return `${theme.fg("dim", "⏭ ")}${label}${theme.fg("dim", ": skipped")}`;
+				}
+				if (answer.entries.length === 0) {
+					return `${theme.fg("dim", "· ")}${label}${theme.fg("dim", ": no answer")}`;
+				}
+				const values = answer.entries
+					.map((entry) =>
+						entry.custom
+							? `${theme.fg("muted", "(typed) ")}${theme.fg("text", entry.value)}`
+							: theme.fg("text", entry.label),
+					)
+					.join(theme.fg("dim", ", "));
+				return `${theme.fg("success", "✓ ")}${label}${theme.fg("muted", ": ")}${values}`;
+			});
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+
+	pi.registerCommand("ask-demo", {
+		description: "Preview the ask_user questionnaire UI with a sample survey",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("The demo needs an interactive UI (TUI or RPC mode).", "error");
+				return;
+			}
+			const questions = normalizeQuestions(demoParams());
+			try {
+				const result = await askQuestions(ctx, questions, {
+					title: "ask_user demo",
+					submitLabel: DEFAULT_SUBMIT_LABEL,
+					signal: ctx.signal,
+				});
+				ctx.ui.notify(
+					result.cancelled
+						? "Demo cancelled"
+						: `Demo finished — ${formatAnswersText(result).split("\n").length} answers`,
+					"info",
+				);
+			} catch (error) {
+				if (error instanceof Error && error.message === "no-ui") {
+					ctx.ui.notify("No UI available for the demo.", "error");
+					return;
+				}
+				throw error;
+			}
+		},
+	});
+}
+
+/** Sample questionnaire used by `/ask-demo` and the README. */
+function demoParams(): AskUserParams {
+	return {
+		title: "ask_user demo",
+		questions: [
+			{
+				id: "scope",
+				label: "Scope",
+				question: "Which parts of the project should this change touch?",
+				multiple: true,
+				options: [
+					{
+						label: "Extension host",
+						description: "Tool registration and lifecycle code",
+						selected: true,
+					},
+					{ label: "TUI component", description: "The interactive questionnaire renderer" },
+					{ label: "Documentation" },
+					{ label: "Tests", selected: true },
+				],
+			},
+			{
+				id: "release",
+				label: "Release",
+				question: "How should the release be versioned?",
+				options: [
+					{ label: "Patch", description: "Bug fixes only (0.0.x)" },
+					{ label: "Minor", description: "Backwards-compatible features (0.x.0)" },
+					{ label: "Major", description: "Breaking changes (x.0.0)" },
+				],
+			},
+			{
+				id: "notes",
+				label: "Notes",
+				question: "Anything else I should know?",
+				required: false,
+				placeholder: "Type a note, or leave empty…",
+			},
+		],
+	};
+}