@alexleekt/pi-ask-user-glimpse 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to `@alexleekt/pi-ask-user-glimpse` are documented in this file.
+
+## [0.2.1] — 2026-05-16
+
+### Fixed
+- **AGENTS.md stale references** — Removed references to deleted `util/detect-conflict.ts` and `util/safe-callback.ts` files.
+- **`allowSkip` schema gap** — Added `allowSkip` parameter to the `defineTool` schema so the LLM can request partial questionnaire submission.
+- **`visual-qa.ts` non-existent event** — Removed `"ready"` event listener which is not declared in `glimpseui.d.ts`.
+- **Tailwind CSS build warning** — Fixed by running Vite from the `webview/` directory so Tailwind resolves content paths correctly.
+- **`validate.ts` placeholder check** — Now checks for exact placeholder `/*ASK_USER_PAYLOAD*/` instead of substring match.
+- **Missing `pi-ai` peer dependency** — Added `@earendil-works/pi-ai` to `peerDependencies` since `index.ts` imports `StringEnum` from it.
+- **Repeated `window.glimpse.send` type assertion** — Extracted to `webview/src/util/glimpse.ts` helper with `sendToGlimpse()` and `sendCancelled()`.
+
+### Added
+- **CONTRIBUTING.md** — Developer setup, build instructions, and pre-submission checklist.
+- **README badges** — npm version and MIT license shields.
+- **`engines` field** — Requires Node.js >= 18.0.0.
+- **`CHANGELOG.md` in npm files** — Now included in the published tarball.
+- **`.jj/` in `.gitignore`** — Jujutsu working directory ignored.
+
+## [0.2.0] — 2026-05-16
+
+### Added
+- **Two-panel layout with markdown context** — When `context` is provided, the dialog splits 40/60: left panel renders context as markdown (via `marked`), right panel shows the question and options. The question title spans the full width as a global header.
+- **Progress bar and answered counter** in Questionnaire dialogs — thin `h-1` bar + "N / M answered" text.
+- **Auto-scroll to first unanswered question** on Questionnaire open.
+- **Auto-focus first option** in SingleSelect and MultiSelect when search box is hidden (≤6 options).
+- **Auto-focus search input** when visible.
+- **Submit loading state** — button text changes to "Submitting…" and is disabled across all dialog types, preventing double-clicks.
+- **Platform-aware keyboard hints** — shows `⌘+Enter` on macOS, `Ctrl+Enter` elsewhere.
+- **Inline SVG icons** for radio buttons and checkboxes (crisp at any scale, replaces text-based `✓` and CSS circles).
+- **ARIA roles** — `role="listbox"`, `role="option"`, `aria-selected`, `aria-multiselectable`, `aria-checked`, `aria-expanded` across all option lists.
+- **ErrorBoundary** around each panel in `App.tsx` — catches runtime React errors gracefully instead of crashing the webview.
+- **Empty search state** — "No matching options" message with guidance when filter returns zero results.
+- **"Clear all" link** in MultiSelect to reset all selections in one click.
+- **Comment existence indicator** — button label changes from "Add comment" to "Edit comment" when text exists.
+- **HTML sanitization** in `ContextPanel` — strips `<script>` tags and `on*` event handlers before `dangerouslySetInnerHTML`.
+- **Questionnaire freeform auto-focus** — textarea gets focus on mount for the first unanswered freeform question.
+
+### Changed
+- **Window size** — increased from `640×480` to `1200×900` to accommodate the two-panel layout and long option lists.
+- **Option descriptions** — moved from a destructive sidebar preview pane to always-visible inline text with a left border indent.
+- **"Other" button** — renamed to "Custom" and moved from bottom of scrollable list to directly under the search box.
+- **Search box** — now conditional: hidden when `options.length <= 6` and `!allowFreeform`, reducing clutter for simple questions.
+- **Cancel button** — changed from bordered secondary button to ghost style (no border, muted text) to reduce accidental clicks.
+- **MultiSelect "N selected" badge** — moved from bottom bar to a primary-colored chip in the header area.
+- **Comment toggle** — changed from invisible underlined text to an inline SVG icon button with hover background.
+- **Keyboard hint placement** — moved from orphaned `text-xs` above buttons to inline with the action bar.
+- **Questionnaire spacing** — tightened from `space-y-6` to `space-y-3`.
+- **Questionnaire freeform input** — changed from `<input type="text">` to `<textarea rows={3}>`.
+- **Description border color** — `border-border` → `border-muted-foreground/30` for visible contrast in both light and dark modes.
+- **Custom button query truncation** — long queries are truncated to 30 chars with "…".
+- **Response trimming** — `response-formatter.ts` now trims freeform text and questionnaire answers.
+
+### Fixed
+- **SingleSelect preview pane bug** — clicking to read a description no longer deselects the current choice.
+- **Questionnaire `allAnswered` bug** — empty freeform strings no longer count as "answered".
+- **SingleSelect keyboard Enter bypass** — `isSubmitting` guard now respected when selecting via keyboard.
+- **Terminal fallback context** — `payload.context` was completely ignored in TUI fallback; now prepended to all prompts.
+- **Terminal multi-select freeform** — picking "Other" no longer discards all prior selections.
+- **Terminal questionnaire freeform** — open-ended questions now show context if provided.
+- **`ctx.hasUI` guard** in `/ask-debug` — replaced crash-risk `ctx.ui.notify()` with `console.warn()`.
+- **Dead code** — removed unused `util/safe-callback.ts` and cleaned up `tsconfig.json` / `package.json` `files` array.
+- **README** — synced all stale references (preview pane → inline descriptions, Other → Custom, 640×480 → 1200×900).
+
+## [0.1.1] — 2026-05-16
+
+### Added
+- Keyboard shortcuts in all webview dialogs:
+  - `Escape` — Close open comment textarea; if none open, cancel dialog
+  - `Enter` — Select+submit focused option (SingleSelect), submit questionnaire (Questionnaire), toggle option (MultiSelect/Questionnaire with Space)
+  - `ArrowUp`/`ArrowDown` — Navigate options with roving tabindex (SingleSelect, MultiSelect)
+  - `Space` — Toggle multi-select options
+  - `Ctrl+Enter` — Submit freeform/ questionnaire
+  - `Tab` — Natural focus movement
+- Visual focus ring (`ring-2 ring-ring`) on keyboard-focused options
+
+### Changed
+- Extracted shared types (`AskUserPayload`, `Question`, `QuestionOption`) from `tool/ask-user.ts` and `webview/src/App.tsx` into `shared/ask-user.ts`. Both server and webview now import from the single source of truth.
+- **Questionnaire `kind` consistency:** WebView and terminal fallback now send `kind: "questionnaire"` with per-question `kind` in `questionnaireDetails` (either `"selection"` or `"freeform"`). Previously all questionnaire answers were incorrectly labeled as `"selection"`.
+
+### Fixed
+- **Critical:** `allAnswered` check in Questionnaire no longer rejects empty-string freeform answers with strict equality (`=== ""`). Now correctly allows empty strings as valid freeform responses while still requiring non-empty arrays for multi-select answers.
+- **Payload injection:** Production code in `tool/ask-user.ts` now properly escapes `<`, `>`, and `&` as `\u003c`, `\u003e`, `\u0026` when serializing JSON into the HTML template, preventing HTML injection attacks. Test scripts updated to match.
+- **`resolveWebviewHtml` error propagation:** File-not-found errors now include the full list of paths tried and a clear instruction (`Run 'npm run build' first`), instead of an unhelpful generic error.
+- **`displayMode` warning:** Runtime warning added when `displayMode` parameter is passed, since Glimpse always opens a centered dialog regardless of the parameter value. Previously the parameter was silently ignored.
+
+## [0.1.0] — 2026-05-16
+
+### Added
+- Single-select dialog with searchable options and split-pane description preview
+- Multi-select dialog with checkbox-style selection
+- Freeform dialog with full-height textarea
+- Questionnaire dialog with per-question options (single-select, multi-select, or freeform)
+- Native WebView rendering via glimpseui (macOS WKWebView / Linux GTK4 / Windows WebView2)
+- Terminal fallback when glimpseui native host is unavailable
+- `/ask-debug` slash command for manual dialog testing
+- Self-contained webview bundle (single inlined HTML file, zero external requests)
+- Dark mode support via `prefers-color-scheme`
+
+### Fixed
+- **Critical:** Test scripts (`validate.ts`, `smoke-test.ts`, `visual-qa.ts`) now properly escape `>`, `&`, and `<` when injecting JSON into HTML, matching production escaping
+- **Bug:** MultiSelect no longer allows empty submission when a search query is present but no option is selected
+- **Dead code:** Removed unreachable `getQuestions` fallback in Questionnaire component
+- **Config:** Removed stale `@earendil-works/pi-tui` peer dependency (never imported)
+- **Config:** Added `prepack` script to ensure webview bundle is built before `npm publish`
+- **Config:** Simplified `tsconfig.json` to use `noEmit: true` (Pi loads `.ts` directly)
+- **Cleanup:** Removed ~24 duplicate stopwords from `STOPWORDS` set
+- **Types:** Fixed `getInfo()` return type in hand-written `glimpseui.d.ts` (`void` → `unknown`)
+
+

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to pi-ask-user-glimpse
+
+Thanks for your interest in improving `@alexleekt/pi-ask-user-glimpse`!
+
+## Development Setup
+
+```bash
+git clone https://github.com/alexleekt/pi-ask-user-glimpse.git
+cd pi-ask-user-glimpse
+npm install
+```
+
+## Building
+
+```bash
+npm run build        # build CSS + webview bundle
+npm run check        # dry-run npm pack
+```
+
+## Testing
+
+```bash
+npm run validate     # checks dist exists, placeholder present, binary found
+npm run validate:gui # same + opens actual WebView for visual check
+npx tsx scripts/smoke-test.ts     # opens WebView for 2s
+npx tsx scripts/visual-qa.ts      # cycles through all 5 scenarios
+```
+
+## Code Style
+
+- **Indentation:** 2 spaces (TypeScript)
+- **Imports:** Use `.js` extensions on relative imports (NodeNext module resolution)
+- **Console output:** Use `[pi-ask-user-glimpse]` prefix for all `console.warn`/`console.error`
+- **Peer deps:** Only list `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` in `peerDependencies`
+
+## Security Note
+
+If you modify payload injection or test scripts, ensure HTML escaping matches production:
+```ts
+JSON.stringify(payload)
+  .replace(/</g, "\\u003c")
+  .replace(/>/g, "\\u003e")
+  .replace(/&/g, "\\u0026")
+```
+
+## Before Submitting
+
+- [ ] `npm run build` passes
+- [ ] `npx tsc --noEmit` passes
+- [ ] `npm run check` shows the expected files
+- [ ] `npm run validate` passes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Lee
+
+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

@@ -0,0 +1,272 @@
+# @alexleekt/pi-ask-user-glimpse
+
+[![npm version](https://img.shields.io/npm/v/@alexleekt/pi-ask-user-glimpse.svg)](https://www.npmjs.com/package/@alexleekt/pi-ask-user-glimpse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Pi extension that replaces `ask_user` with rich native WebView dialogs powered by [glimpseui](https://npmjs.com/package/glimpseui) and styled with shadcn/ui design tokens.
+
+## Features
+
+- **Single-select** — searchable option list with inline descriptions
+- **Multi-select** — checkbox-style selection with submit/cancel
+- **Freeform** — textarea input for open-ended responses
+- **Questionnaire** — cards in a vertical list for structured questions, each with its own options
+- **Native WebView** — renders in a real window (macOS WKWebView / Linux GTK4 / Windows WebView2)
+- **Terminal fallback** — gracefully degrades to TUI prompts when glimpseui is unavailable
+
+
+## Install
+
+```bash
+pi install npm:@alexleekt/pi-ask-user-glimpse
+```
+
+Requires a Pi coding agent harness with extension support (e.g. `@earendil-works/pi-coding-agent`).
+
+## Usage
+
+Once installed, the extension automatically replaces the built-in `ask_user` tool. The LLM calls it the same way as before — you don't need to do anything different.
+
+### Single Select
+
+Ask the user to pick exactly one option:
+
+```json
+{
+  "question": "Which database should we use?",
+  "context": "We need something reliable for a production workload.",
+  "options": [
+    { "title": "PostgreSQL", "description": "Relational, proven, great ecosystem" },
+    { "title": "SQLite", "description": "Zero-config, embedded, serverless" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true,
+  "allowComment": true
+}
+```
+
+The dialog shows a full-width question header and a two-panel layout. When `context` is provided, the left panel renders it as markdown for reference while the right panel shows the searchable option list. Option descriptions appear inline below each title. The "Custom" button under the search box lets the user submit a freeform answer.
+
+### Multi Select
+
+Ask the user to pick multiple options:
+
+```json
+{
+  "question": "Which features should we implement first?",
+  "context": "MVP is due in 2 weeks. Pick the most impactful items.",
+  "options": [
+    { "title": "OAuth login", "description": "Google + GitHub sign-in" },
+    { "title": "Real-time sync", "description": "WebSocket live updates" },
+    { "title": "Email notifications", "description": "Digest + instant alerts" }
+  ],
+  "allowMultiple": true,
+  "allowFreeform": true,
+  "allowComment": true
+}
+```
+
+Each option has a checkbox. A "Clear all" link resets selections. Submit is disabled until at least one item is selected.
+
+### Freeform
+
+Ask an open-ended question with no predefined options:
+
+```json
+{
+  "question": "Describe the ideal user onboarding flow.",
+  "context": "We're redesigning first-time experience. Be specific about steps, copy, and timing.",
+  "allowFreeform": true
+}
+```
+
+Shows a full-height textarea with platform-aware keyboard hints (⌘+Enter on macOS, Ctrl+Enter elsewhere). Submit is disabled until text is entered.
+
+### Questionnaire
+
+Ask multiple structured questions in one dialog:
+
+```json
+{
+  "question": "Project scoping questionnaire",
+  "context": "Answer each question to help us scope accurately.",
+  "questions": [
+    {
+      "title": "Database",
+      "description": "Which database should we use?",
+      "options": [
+        { "title": "PostgreSQL", "description": "Relational, proven" },
+        { "title": "SQLite", "description": "Zero-config" }
+      ],
+      "allowMultiple": false
+    },
+    {
+      "title": "Cache layer",
+      "description": "Select caching strategies",
+      "options": [
+        { "title": "Redis", "description": "In-memory key-value" },
+        { "title": "Memcached", "description": "Simple caching" }
+      ],
+      "allowMultiple": true
+    },
+    {
+      "title": "Notes",
+      "description": "Any additional thoughts?"
+    }
+  ],
+  "allowComment": true
+}
+```
+
+Each question is shown as a card with a progress bar at the top. Questions with `options` render as single-select (radio) or multi-select (checkbox) depending on `allowMultiple`. Questions without `options` render as a textarea. The dialog auto-scrolls to the first unanswered question on open. The comment button shows "Edit comment" when text exists. Submit is disabled until all questions have a non-empty answer, unless `allowSkip: true` is set.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `question` | `string` | *(required)* | The question to ask |
+| `context` | `string` | — | Additional context shown in a left-side markdown panel |
+| `options` | `Array<string \| {title, description?}>` | — | Options for flat single/multi-select mode |
+| `questions` | `Array<{title, description?, options?, allowMultiple?}>` | — | Questions for questionnaire mode. When present, `options` is ignored. Each question can have its own `options` (same shape as top-level `options`) and `allowMultiple`. Questions without `options` render as freeform textareas. |
+| `allowMultiple` | `boolean` | `false` | Allow selecting multiple options |
+| `allowFreeform` | `boolean` | `true` | Show a freeform "Custom" option |
+| `allowComment` | `boolean` | `false` | Collect an optional comment after selection |
+| `allowSkip` | `boolean` | `false` | Allow submitting a questionnaire without answering all questions (questionnaire mode only) |
+| `followCursor` | `boolean` | `false` | Make the 1200×900 dialog follow the terminal cursor |
+| `displayMode` | `"overlay" \| "inline"` | — | Legacy option; ignored (always centered dialog) |
+
+## Development
+
+```bash
+git clone https://github.com/alexleekt/pi-ask-user-glimpse.git
+cd pi-ask-user-glimpse
+npm install
+```
+
+### Build the webview bundle
+
+```bash
+npm run build        # builds CSS + Vite webview → dist/index.html
+```
+
+### Dev server for webview
+
+```bash
+npm run dev:webview  # Vite dev server on http://localhost:5173
+```
+
+### Validate
+
+```bash
+npm run validate     # checks dist exists, placeholder present, binary found
+npm run validate:gui # same + opens actual WebView for visual check
+npm run check        # dry-run npm pack
+```
+
+## Auto-Detection: When `ask_user` Is Used Automatically
+
+Some skills instruct the agent to "ask questions one at a time" but never tell it to **use a tool** — so the agent writes plain text, bypassing the rich WebView dialog.
+
+This extension auto-detects question-oriented sessions and injects a system-prompt mandate that tells the LLM to use `ask_user` for every question.
+
+### Auto-detection
+
+Before each LLM turn, the extension checks:
+
+1. **Known question skills** — `grill-with-docs`, `questionnaire`, `interview`, `grill`
+2. **Language patterns** in the system prompt — "ask the questions one at a time", "interview me", "grilling session", "wait for feedback"
+3. **Manual toggle** — `/ask-style` overrides the behavior for the current session
+
+When triggered, it appends: "You MUST use `ask_user` for every question. Do NOT write free-form text."
+
+### Manual toggle: `/ask-style`
+
+Override auto-detection for the current session:
+
+```
+/ask-style
+```
+
+Cycles through three states:
+
+| State | Behavior |
+|-------|----------|
+| **AUTO** *(default)* | Auto-detect question sessions by skill name + language patterns |
+| **Always Dialog** | Always use `ask_user` for every question, regardless of detection |
+| **Plain Text** | Disable everything — let the agent write questions as plain text |
+
+The setting is persisted in the session and survives restarts.
+
+### Token cost
+
+The injected mandate is ~100 tokens. It is only appended when detection triggers, so normal conversations pay nothing extra.
+
+## Slash Command: `/ask-last`
+
+When the assistant writes a question as free-form text (bypassing `ask_user`), use this command to retroactively open the rich dialog:
+
+```
+/ask-last
+```
+
+### How it works
+
+1. Finds the last assistant message in the session
+2. Extracts all sentences ending with `?`
+3. If one question → opens a **freeform** dialog with the full message as context
+4. If multiple questions → opens a **questionnaire** with each question as an item
+5. Sends your answer back into the conversation as a user message
+
+This is useful when:
+- A skill or the agent itself wrote a question as plain text
+- You want to answer via the rich WebView instead of typing inline
+- The agent asked multiple things and you want to answer them all at once
+
+## Slash Command: `/ask-debug`
+
+Open a debug prompt that lets you manually test each dialog type:
+
+```
+/ask-debug
+```
+
+Options: `single-select`, `multi-select`, `freeform`, `questionnaire`. The result is shown as a Pi notification.
+
+## Window Behavior
+
+- **Title bar** — shows a condensed version of the question text (up to 3 content words)
+- **Centered dialog** — normal stacking, not floating
+- **Size** — 1200×900 by default
+- **Cursor follow** — off by default; enable with `followCursor: true`
+- **Dark mode** — automatically follows the system `prefers-color-scheme` setting
+
+## Architecture
+
+```
+index.ts              → Pi extension entrypoint (tool + command registration)
+tool/ask-user.ts      → constructs payload, injects into HTML, calls glimpseui.prompt()
+tool/response-formatter.ts → normalizes WebView response for Pi
+webview/src/components/     → SingleSelect, MultiSelect, Questionnaire, Freeform, ContextPanel, ErrorBoundary
+fallback/terminal-prompt.ts → readline fallback when WebView unavailable
+webview/              → Vite + React + Tailwind app
+  src/components/     → SingleSelect, MultiSelect, Questionnaire, Freeform
+  dist/index.html     → single-file bundle (inlined JS + CSS)
+```
+
+## Troubleshooting
+
+### "Could not find webview bundle"
+
+Run `npm run build` to generate `dist/index.html`. The extension cannot work without the webview bundle.
+
+### WebView does not open (terminal fallback instead)
+
+The extension falls back to TUI prompts when the glimpseui native host is unavailable. This is normal on headless systems or if the native binary is missing. Check `npm run validate` to see if the binary is detected.
+
+### Dialog shows "Missing or invalid ask_user payload"
+
+This means the HTML payload injection failed. Ensure `dist/index.html` contains the `/*ASK_USER_PAYLOAD*/` placeholder. Run `npm run build` to regenerate.
+
+## License
+
+MIT