pi-soly 0.3.0 → 0.5.0

package/ask/README.md

@@ -0,0 +1,135 @@
+# pi-ask — Claude Code-style multi-question picker for pi
+
+A small pi-coding-agent extension that registers one tool (`ask_pro`) for
+showing a **tabbed, multi-question picker** in pi's TUI. Inspired by Claude
+Code's `AskUserQuestion`.
+
+## Features
+
+- **Multi-question** — pass a list of questions; the user navigates between
+  them with `Tab` / `Shift+Tab` or arrow keys
+- **Numbered options** — `1`–`4` instant-pick
+- **Recommended answer** — first option (or the one with `recommended: true`)
+  is marked ⭐
+- **Single-select** (default) — Enter on an option auto-advances to the next
+  question; on the last question, Enter submits
+- **Multi-select** — Enter toggles checkboxes; the last question shows a
+  visible "Submit" row
+- **Cancelled detection** — `Esc` resolves `{cancelled: true}`
+
+## Usage from an LLM
+
+```ts
+ask_pro({
+  questions: [
+    {
+      header: "Auth",                         // 1-2 word tab label
+      question: "Which auth approach?",
+      options: [
+        { label: "JWT in httpOnly cookie", description: "Stateless, scales horizontally", recommended: true },
+        { label: "JWT in localStorage",     description: "Simpler client, XSS risk" },
+        { label: "Server sessions + Redis",  description: "Revocable, but extra dep" },
+      ],
+      multiSelect: false,
+    },
+    {
+      header: "Tokens",
+      question: "Token storage?",
+      options: [
+        { label: "httpOnly cookie" },
+        { label: "Bearer in Authorization" },
+      ],
+    },
+  ],
+})
+```
+
+Result:
+
+```ts
+// user picked "JWT in httpOnly cookie" + "Bearer in Authorization":
+{ answers: { 0: 0, 1: 1 } }
+
+// user pressed Esc:
+{ cancelled: true }
+```
+
+## UX
+
+```
+┌─ pi-ask — 2 questions ────────────────────────────────────────┐
+│ ◉ Auth    ○ Tokens                                              │
+│                                                                 │
+│ Q1 of 2: Which auth approach?                                  │
+│                                                                 │
+│   ❯ ⭐ JWT in httpOnly cookie                                   │
+│       Stateless, scales horizontally                            │
+│                                                                 │
+│     JWT in localStorage                                         │
+│     Simpler client, XSS risk                                    │
+│                                                                 │
+│     Server sessions + Redis                                     │
+│     Revocable, but extra dependency                              │
+│                                                                 │
+│ ↑↓ navigate · 1-3 pick · tab/→ next · ⏎ next · esc cancel      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `↑` / `k` | Move option up |
+| `↓` / `j` | Move option down |
+| `1` – `4` | Instant-pick that option |
+| `Tab` / `→` | Next question |
+| `Shift+Tab` / `←` / `Backspace` | Previous question |
+| `Space` | Multi-select only: toggle the current option. On "Other…", opens the input dialog. |
+| `Enter` | **Single-select:** confirm + advance (or submit on last). **Multi-select:** advance to next question (or submit on last + all answered). Does NOT toggle. |
+| `Esc` | Cancel (returns `{cancelled: true}`) |
+
+Multi-select follows the Claude Code convention: **Space toggles, Enter
+advances/submits**. Single-select uses Enter as the universal action key
+(toggle/pick + advance). When you're on the last question and all
+questions are answered, the footer shows `⏎ submit` in accent color.
+
+## Limits
+
+- 2–4 options per question (more is bad UX; the picker is meant for focused
+  choices, not long lists)
+- 1–6 questions per call (more = tab-switching fatigue)
+- At most 1 `recommended: true` per question
+- TUI and RPC modes only (`hasUI: true`); print mode returns an error
+
+## Setup
+
+Drop the directory in `~/.pi/agent/extensions/`:
+
+```bash
+ls ~/.pi/agent/extensions/pi-ask/
+# index.ts picker.ts tests/ package.json tsconfig.json README.md
+```
+
+pi auto-discovers and loads it on next start. The `ask_pro` tool is then
+available to the LLM. No config required.
+
+## Development
+
+```bash
+cd ~/.pi/agent/extensions/pi-ask
+bun test              # runs tests/picker.test.ts
+bun run typecheck     # tsc --noEmit
+```
+
+CI: not configured (this is a single-file TUI component, low risk).
+Add `.github/workflows/ci.yml` if you want green-tick PRs.
+
+## Why a separate extension?
+
+The picker is **generic** — any pi extension (soly, your own tool, etc.) can
+use `ask_pro` to drive multi-question Q&A without re-implementing the TUI.
+Keeping it separate from soly means:
+
+- soly stays focused on the plan/execute/discuss workflow
+- other extensions can adopt the same UX pattern
+- the picker can evolve independently (new key bindings, themes, layouts)

package/ask/index.ts

@@ -0,0 +1,218 @@
+// =============================================================================
+// index.ts — pi-ask extension entry point
+// =============================================================================
+//
+// Registers one LLM tool: `ask_pro`. Lets the LLM ask the user a list of
+// questions at once via a Claude Code-style tabbed picker (tabs, numbered
+// options, ⭐ recommended answer, optional multi-select). All answers
+// returned in a single call.
+//
+// Usage from another extension / LLM:
+//   ask_pro({
+//     questions: [
+//       { header: "Auth", question: "Which auth?", options: [...], multiSelect: false },
+//       { header: "Tokens", question: "Token storage?", options: [...] },
+//     ]
+//   })
+// → { answers: { 0: 1, 1: 0 } }   or   { cancelled: true }
+//
+// Generic — not soly-specific. Any pi extension that needs multi-question
+// Q&A can use this.
+// =============================================================================
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { AskProComponent, type AskProResult } from "./picker.ts";
+import { buildAskProSection } from "./prompt.ts";
+
+export default function piAskExtension(pi: ExtensionAPI) {
+	// Inject a "when to use ask_pro" section into the system prompt so the
+	// LLM reaches for the picker at the right times (and avoids overusing
+	// it for trivial yes/no or open-ended questions).
+	pi.on("before_agent_start", async (event) => {
+		return {
+			systemPrompt: event.systemPrompt + buildAskProSection(),
+		};
+	});
+
+	pi.registerTool({
+		name: "ask_pro",
+		label: "pi-ask ask_pro",
+		description:
+			"Ask the user multiple questions at once via a Claude Code-style tabbed picker. Each question is a tab at the top. Options are numbered (1-N instant-pick), the recommended answer is marked ⭐. Supports single-select (default, auto-advance on pick) and multi-select (Enter toggles, last question shows Submit). All answers returned in one call. Use for progressive Q&A flows like `soly discuss`.",
+		parameters: Type.Object({
+			questions: Type.Array(
+				Type.Object({
+					header: Type.String({
+						description: "Short label for the tab (1-2 words, max 12 chars).",
+					}),
+					question: Type.String({
+						description: "The full question to ask.",
+					}),
+					options: Type.Array(
+						Type.Object({
+							label: Type.String({
+								description: "Short label (1-5 words).",
+							}),
+							description: Type.Optional(
+								Type.String({
+									description: "1-2 sentence explanation. Shown below the label.",
+								}),
+							),
+							recommended: Type.Optional(
+								Type.Boolean({
+									description: "Mark as ⭐ recommended answer.",
+								}),
+							),
+						}),
+						{ description: "2-4 concrete options." },
+					),
+					multiSelect: Type.Optional(
+						Type.Boolean({
+							description:
+								"If true, user can pick multiple (checkboxes, Enter toggles). If false (default), single-select with auto-advance.",
+						}),
+					),
+				}),
+				{
+					description:
+						"Questions to ask, in tab order. Max ~5 recommended (more hurts UX).",
+				},
+			),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			// --- safety: UI required ---
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "ask_pro requires a UI-capable session (TUI or RPC mode). Run from the interactive pi TUI.",
+						},
+					],
+					details: { error: "no_ui", mode: ctx.mode },
+				};
+			}
+
+			// --- validation ---
+			if (params.questions.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "ask_pro: at least one question is required" },
+					],
+					details: { error: "no_questions" },
+				};
+			}
+			if (params.questions.length > 6) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `ask_pro: ${params.questions.length} questions is a lot; max 6 recommended for UX (more = more tab-switching fatigue).`,
+						},
+					],
+					details: { error: "too_many_questions", count: params.questions.length },
+				};
+			}
+			for (let i = 0; i < params.questions.length; i++) {
+				const q = params.questions[i];
+				if (!q) continue;
+				if (q.options.length < 2 || q.options.length > 4) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `ask_pro: Q${i + 1} ("${q.header}") has ${q.options.length} options, need 2-4.`,
+							},
+						],
+						details: {
+							error: "bad_option_count",
+							questionIdx: i,
+							count: q.options.length,
+						},
+					};
+				}
+				// Recommend at most one ⭐ per question
+				const recommendedCount = q.options.filter((o) => o.recommended).length;
+				if (recommendedCount > 1) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `ask_pro: Q${i + 1} ("${q.header}") has ${recommendedCount} recommended options, at most 1 allowed.`,
+							},
+						],
+						details: { error: "multiple_recommended", questionIdx: i },
+					};
+				}
+			}
+
+			// --- show the picker ---
+			const result = await ctx.ui.custom<AskProResult>(
+				(tui, theme, keybindings, done) => {
+					// pi-coding-agent's Theme is structurally compatible with our
+					// AskProTheme (same fg/bold signatures); the color type is
+					// just stricter on the agent's side. Cast to satisfy TS.
+					const askTheme = theme as unknown as ConstructorParameters<typeof AskProComponent>[0]["theme"];
+					return new AskProComponent({
+						questions: params.questions,
+						theme: askTheme,
+						keybindings,
+						done,
+						// Bridge to the parent's UI for the "Other…" text input.
+						// The picker stays decoupled from ExtensionContext.
+						onRequestInput: async (req) => {
+							if (!ctx.hasUI) return undefined;
+							return (await ctx.ui.input(req.title, req.placeholder)) ?? undefined;
+						},
+						title: `pi-ask — ${params.questions.length} question${params.questions.length > 1 ? "s" : ""}`,
+					});
+				},
+			);
+
+			// --- handle the result ---
+			if (result.cancelled) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "(user cancelled the picker — no answers captured)",
+						},
+					],
+					details: { cancelled: true },
+				};
+			}
+
+			const answers = result.answers ?? {};
+			// Pretty-print for the LLM
+			const out: string[] = ["User answers:"];
+			for (let i = 0; i < params.questions.length; i++) {
+				const q = params.questions[i];
+				if (!q) continue;
+				const a = answers[i];
+				if (a === undefined) {
+					out.push(`  Q${i + 1} (${q.header}): (no answer)`);
+				} else if (Array.isArray(a)) {
+					const parts: string[] = [];
+					for (const item of a) {
+						if (typeof item === "number") {
+							parts.push(q.options[item]?.label ?? `?${item}`);
+						} else {
+							parts.push(`"${item}"`);
+						}
+					}
+					out.push(`  Q${i + 1} (${q.header}) [multi]: ${parts.join(", ")}`);
+				} else if (typeof a === "number") {
+					out.push(`  Q${i + 1} (${q.header}): ${q.options[a]?.label ?? `?${a}`}`);
+				} else {
+					out.push(`  Q${i + 1} (${q.header}) [Other]: "${a}"`);
+				}
+			}
+
+			return {
+				content: [{ type: "text", text: out.join("\n") }],
+				details: { answers },
+			};
+		},
+	});
+}

package/ask/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pi-asked",
+  "version": "0.2.0",
+  "description": "Claude Code-style multi-question picker for pi. Tabbed picker with recommended answers, multi-select, and Other… text input.",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@earendil-works/pi-tui": "0.78.1",
+    "@types/node": "^25.9.1",
+    "bun-types": "^1.3.14",
+    "typebox": "1.1.38",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "index.ts",
+    "picker.ts",
+    "prompt.ts"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "ask-user",
+    "multi-question",
+    "picker"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "http://git.local.stbl/lowern1ght/pi-soly.framework.git",
+    "directory": "packages/pi-ask"
+  }
+}