pi-ask-user-x 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dogalyir contributors
+
+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,168 @@
-# Temporary Holding Version
+# pi-ask-user-x
 
-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.
+Bilingual structured questionnaire extension for the Pi coding agent (`@earendil-works/pi-coding-agent`).
+
+## Overview & Architecture
+
+`pi-ask-user-x` provides the `ask_user` tool for interactive user questionnaires, preference elicitation, and architectural decision trees.
+
+- **Non-Interception & Tool Separation**: The separate `ask_user_question` plugin is **not intercepted**, patched, or monkey-patched. Models invoke `ask_user` directly to ask structured questions with single or multiple choices, or open freeform input, without global state mutations.
+- **Dual Execution Modes**:
+  - **Co-operative with `pi-translate-x`**: When `pi-translate-x` (>=0.1.3) is active and enabled, question headers, prompts, descriptions, and predefined options are dynamically translated into the user's target language via the versioned translation service (`TranslationService`, protocol v1 over `pi.events`). Custom user prose and notes are reverse-translated back to English for the LLM. Translation is a presentation implementation detail—the model tool name, label, and description remain clean and neutral.
+  - **Standalone Mode**: When `pi-translate-x` is absent or disabled at launch, `pi-ask-user-x` operates standalone in canonical English without failure. When an active translation service is detected but incompatible, malformed, or fails rediscovery/retry, users are presented with an explicit recovery choice (Retry discovery, Continue in English, or Cancel questionnaire) rather than silently degrading. Once an enabled service is discovered, answer translation obligation is pinned: custom user prose and notes are never submitted raw to the LLM without translation or explicit user recovery choice.
+- **English-Canonical Contract & Stable IDs**: Predefined choices resolve strictly by stable, immutable string identifiers (`id`), completely independent of translated display text or duplicate localized labels. Predefined option choices are never back-translated. The model-facing tool arguments and return results remain strictly canonical English.
+- **Submit-Only Privacy & Persistence**: Only confirmed, submitted questionnaire answers and their durable bilingual display snapshot are persisted to the session transcript (as context-excluded custom entries of type `pi-ask-user-x:questionnaire`). In-progress drafts, uncommitted answers, and cancelled questionnaire sessions are discarded from memory and never written to transcript storage. Persisted records are static; changing translator settings later does not re-translate or mutate session history. Durable transcript records are rendered visually for the human user but excluded from LLM context injection.
+
+## Question Types and Configuration
+
+The `ask_user` tool supports 1 to 8 structured questions per invocation:
+
+| Question Type | Behavior & Fields |
+|---|---|
+| `single` (default) | Single-select radio choices. Pressing `Enter` selects the option and advances. Allows custom supplemental text alongside selection when `allowCustom: true`. |
+| `multi` | Multi-select checkbox choices. Toggled with `Space`. Enforces optional `minSelections` and `maxSelections` constraints. Allows custom supplemental text when `allowCustom: true`. |
+| `text` | Pure free-form text input. Options are omitted; uses `textPlaceholder`, `textMinLength`, and `textMaxLength`. |
+
+- **Options**: Each option defines a unique `id` (e.g. `'postgres'`), display `label`, optional `description`, and optional Markdown `preview`.
+- **Supplemental Custom Input**: When `allowCustom: true` (default for `single` and `multi`), users can press `c` to enter custom text. For single-select questions, custom text is preserved as supplemental qualification alongside the selected choice, rather than a conflicting radio indicator.
+- **Notes**: Supports per-question notes (press `n` on any question row) and global questionnaire notes (edited in the Review tab).
+- **Validation**: Enforces mandatory fields (`required: true`), selection count bounds (`minSelections`, `maxSelections`), and text lengths. Attempted submissions with invalid fields announce warnings and automatically jump focus to the first invalid row.
+- **Explicit Mark-Empty**: Optional questions support explicit blank confirmation (`e` shortcut) to distinguish conscious skips from unvisited rows.
+
+## Terminal UI (TUI) & Layout Responsiveness
+
+The TUI component (`QuestionnaireTUIComponent`) provides an accessible, fully responsive terminal interface:
+- **Screen Layouts**: Responsive side-by-side (>= 80 columns), stacked preview (60–80 columns), and compact (< 60 columns) modes.
+- **Height-Bounded Viewport**: Computes `termRows` before checking cached renders, caching terminal height alongside width. Terminal height resizes (e.g. 24 -> 8 -> 4 rows) at the same width reflow immediately without requiring manual `invalidate()`.
+- **Markdown Previews**: Syntax-highlighted code blocks in previews (via public `Markdown` and `getMarkdownTheme()`). Focusable with `p`, scrollable with Up/Down/PageUp/PageDown without clipping.
+- **Review Tab**: Accessible via `Tab`/`Shift-Tab`, listing all question statuses, answers, validation errors, global notes, and submit trigger. Pressing `Enter` on any row jumps directly to edit that question.
+- **Confirmations**:
+  - Full submit confirmation (`confirm_submit_full`).
+  - Conscious partial submit confirmation (`confirm_submit_partial`), explicitly listing headers and IDs of unanswered questions.
+  - Cancellation confirmation (`confirm_cancel`), confirming before discarding draft responses.
+- **Error Recovery**:
+  - Display translation failure: `[r]` Retry translation, `[e/Enter]` Continue in English, `[c/Esc]` Cancel questionnaire.
+  - Answer translation failure: `[r]` Retry translation, `[e/Enter]` Return to edit drafts, `[c/Esc]` Cancel questionnaire.
+- **Compact Small-Viewport Dialogs**: Early error and confirmation dialogs adapt dynamically to constrained heights (down to height 1) and narrow widths (1, 3, 4, 6, 12 columns). All action choices (`[r]`, `[e/Enter]`, `[c/Esc]` or `[y/Enter]`, `[n/Esc]`) are preserved in discoverable short hints without slicing action lines. Detail messages scroll vertically via Up/Down navigation when viewports are constrained. Truncation uses ANSI-safe width calculations.
+
+## RPC Mode Degradation
+
+When running headless or via RPC (`ctx.mode === "rpc"`), interactive terminal components degrade gracefully to standard dialog methods (`ui.select`, `ui.input`, `ui.confirm`). Rich Markdown previews degrade to text label and description hints.
+
+## Installation & Usage
+
+### Installing Published Packages
+
+Install the companion questionnaire package directly from npm:
+```sh
+pi install npm:pi-ask-user-x
+```
+
+When using alongside `pi-translate-x` for bilingual translation support, ensure `pi-translate-x` is at least version `0.1.3`:
+```sh
+pi install npm:pi-translate-x
+```
+
+### Source Checkout, Migration, and Release Status
+
+- **Tool Name Migration**:
+  - In `pi-ask-user-x@0.1.0` (published on npm): The tool was named `bilingual_questionnaire`.
+  - In `pi-ask-user-x@0.1.1` (prepared in checkout): The tool is renamed to `ask_user` with label `Ask User` and a neutral model description (`structured questions / choices / freeform`).
+- **Published Tarball vs Source**: Version `0.1.0` of `pi-ask-user-x` is verified public latest on npm (integrity `sha512-MYTZ9F1Ll7DKmyeUtq5iAzBF/r6vwomizfeR2WUjr25KK+si36iHINRgMon5WzUcNkxzjnc/mGeWtnG/d1Mdiw==`, owner `carmelocampos`). Because npm enforces package immutability, version 0.1.0 cannot and will not be republished. Version `0.1.1` is prepared in this repository workspace.
+- **Future Automated Releases**: Subsequent releases will be automated via GitHub Actions workflow `.github/workflows/publish-ask-user.yml` triggered exclusively by published GitHub Releases (`GHrelease.published`) with tag `pi-ask-user-x-v<packageversion>`.
+- **npm Trusted Publisher Configuration**:
+  - GitHub repository: `dogalyir/pi-translate-x`
+  - Workflow name: `publish-ask-user.yml`
+  - Environment name: `npm`
+  *(Do not configure the trusted publisher in the npm owner UI until confirmed.)*
+
+### Local Development from Checkout
+
+To run or test both extensions locally from this checkout without loading duplicate extensions:
+```sh
+pi --no-extensions --extension ./src/index.ts --extension ./packages/ask-user/src/index.ts
+```
+
+## Runnable Schema Example
+
+Below is a complete, runnable invocation of `ask_user` demonstrating `single`, `multi`, and `text` question types, markdown previews, supplemental custom text, notes, and selection bounds:
+
+```json
+{
+  "title": "System Architecture Decisions",
+  "description": "Please specify preferences for storage, caching, and custom deployment requirements.",
+  "notes": "Decisions will be recorded in ADR-004.",
+  "questions": [
+    {
+      "id": "database_engine",
+      "header": "Database",
+      "prompt": "Which primary database engine should the microservices utilize?",
+      "description": "Consider ACID guarantees, relational consistency, and read/write access patterns.",
+      "type": "single",
+      "required": true,
+      "allowCustom": true,
+      "options": [
+        {
+          "id": "postgresql",
+          "label": "PostgreSQL",
+          "description": "Relational database with JSONB support, strict ACID compliance, and robust extension ecosystem.",
+          "preview": "```sql\nCREATE TABLE tenants (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  name TEXT NOT NULL,\n  created_at TIMESTAMPTZ DEFAULT now()\n);\n```"
+        },
+        {
+          "id": "mongodb",
+          "label": "MongoDB",
+          "description": "Document-oriented database optimized for flexible schemas and horizontal sharding.",
+          "preview": "```javascript\ndb.tenants.insertOne({\n  name: 'Acme Corp',\n  createdAt: new Date()\n});\n```"
+        }
+      ]
+    },
+    {
+      "id": "caching_layer",
+      "header": "Cache",
+      "prompt": "Select caching technologies to support high-throughput read operations:",
+      "type": "multi",
+      "required": false,
+      "minSelections": 1,
+      "maxSelections": 2,
+      "allowCustom": true,
+      "options": [
+        {
+          "id": "redis",
+          "label": "Redis",
+          "description": "In-memory data store supporting pub/sub, clustering, and rich data structures."
+        },
+        {
+          "id": "memcached",
+          "label": "Memcached",
+          "description": "Simple multithreaded key-value cache."
+        }
+      ]
+    },
+    {
+      "id": "compliance_notes",
+      "header": "Compliance",
+      "prompt": "Specify any regulatory or data residency constraints (e.g. GDPR, HIPAA, FedRAMP):",
+      "type": "text",
+      "required": false,
+      "textPlaceholder": "e.g. EU data residency required; logs retained for 90 days max.",
+      "textMaxLength": 1000
+    }
+  ]
+}
+```
+
+## Testing & Verification Limits
+
+Automated test suites pass deterministically using headless Vitest assertions, mock terminal renderers, and simulated event busses. **No manual assistive technology (AT), hardware cursor, screen-reader, or live terminal/provider verification is claimed.** Manual terminal inspection remains required for physical terminal emulator quirks.
+
+## Documentation & Monorepo Links
+
+For additional architectural details and guides, see the repository documentation:
+- [Questionnaire Guide](https://github.com/dogalyir/pi-translate-x/blob/main/docs/questionnaire.md)
+- [Translation Pipeline Guide](https://github.com/dogalyir/pi-translate-x/blob/main/docs/translation.md)
+- [Release Operations & Verification](https://github.com/dogalyir/pi-translate-x/blob/main/docs/releases.md)
+- [Monorepo Documentation Index](https://github.com/dogalyir/pi-translate-x/blob/main/docs/index.md)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "pi-ask-user-x",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Bilingual structured questionnaire extension for Pi coding agent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogalyir/pi-translate-x.git",
+    "directory": "packages/ask-user"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "22.15.30",
+    "typescript": "5.8.3",
+    "vitest": "5.0.5",
+    "typebox": "1.3.27"
+  }
+}

package/src/domain/chrome.ts

@@ -0,0 +1,109 @@
+export interface UIChromeStrings {
+  readonly reviewAndSubmit: string;
+  readonly reviewTitle: string;
+  readonly reviewHint: string;
+  readonly answeredBadge: string;
+  readonly missingRequiredBadge: string;
+  readonly skippedOptionalBadge: string;
+  readonly globalNotesLabel: string;
+  readonly customLabel: string;
+  readonly noteLabel: string;
+  readonly submitAnswers: string;
+  readonly submitIncomplete: string;
+  readonly submitPartial: string;
+  readonly confirmCancelTitle: string;
+  readonly confirmCancelPrompt: string;
+  readonly confirmCancelYes: string;
+  readonly confirmCancelNo: string;
+  readonly confirmSubmitTitle: string;
+  readonly confirmSubmitPrompt: string;
+  readonly confirmSubmitYes: string;
+  readonly confirmSubmitNo: string;
+  readonly retryTranslation: string;
+  readonly continueInEnglish: string;
+  readonly cancelQuestionnaire: string;
+  readonly retryAnswers: string;
+  readonly returnToEdit: string;
+  readonly previewHeader: string;
+  readonly noPreview: string;
+  readonly addGlobalNotesPrompt: string;
+  readonly addQuestionNotesPrompt: string;
+  readonly typeCustomPlaceholder: string;
+  readonly footerNav: string;
+  readonly footerEdit: string;
+  readonly emptySelectionConfirm: string;
+  readonly skipQuestion: string;
+  readonly doneSelections: string;
+  readonly backQuestion: string;
+  readonly confirmPartialTitle: string;
+  readonly submitAnyway: string;
+  readonly validationFailed: string;
+  readonly requiredBadge: string;
+  readonly optionalBadge: string;
+  readonly markEmpty: string;
+  readonly clearNote: string;
+  readonly clearCustom: string;
+  readonly togglePreview: string;
+  readonly toggleOptions: string;
+  readonly submitConfirmTitle: string;
+  readonly scrollUpMore: string;
+  readonly scrollDownMore: string;
+  readonly previewFocusHint: string;
+  readonly previewScrollHint: string;
+  readonly previewCollapseHint: string;
+}
+
+export const DEFAULT_EN_CHROME: UIChromeStrings = {
+  reviewAndSubmit: "Review & Submit",
+  reviewTitle: "Review & Submit Answers",
+  reviewHint: "Press [Enter] on any question row to jump back and edit it.",
+  answeredBadge: "✓ Answered",
+  missingRequiredBadge: "* Missing - Required",
+  skippedOptionalBadge: "○ Skipped - Optional",
+  globalNotesLabel: "Global Notes",
+  customLabel: "Custom",
+  noteLabel: "Note",
+  submitAnswers: "Submit Answers",
+  submitIncomplete: "Incomplete - Fix Required Questions Above",
+  submitPartial: "Submit Partial Answers (Unanswered Remain)",
+  confirmCancelTitle: "Are you sure you want to cancel?",
+  confirmCancelPrompt: "All entered answers and drafts will be discarded.",
+  confirmCancelYes: "Confirm cancel",
+  confirmCancelNo: "Keep editing",
+  confirmSubmitTitle: "Ready to Submit Questionnaire",
+  confirmSubmitPrompt: "All required questions have been answered. Confirm submission?",
+  confirmSubmitYes: "Submit answers",
+  confirmSubmitNo: "Keep editing",
+  retryTranslation: "Retry translation",
+  continueInEnglish: "Continue in English",
+  cancelQuestionnaire: "Cancel questionnaire",
+  retryAnswers: "Retry translating answers",
+  returnToEdit: "Return to edit drafts",
+  previewHeader: "Preview",
+  noPreview: "(No preview available)",
+  addGlobalNotesPrompt: "(Press Enter to add overall questionnaire notes...)",
+  addQuestionNotesPrompt: "(Add a note for this question...)",
+  typeCustomPlaceholder: "(Type custom answer...)",
+  footerNav: "[Tab/Shift-Tab] Switch Question  [↑/↓] Navigate  [PgUp/PgDn] Page  [p] Preview  [Space] Select  [Enter] Action  [Esc] Cancel",
+  footerEdit: "[Enter] Confirm input  [Esc] Revert/cancel input",
+  emptySelectionConfirm: "[Empty] Confirm empty selection",
+  skipQuestion: "⏭ Skip this question",
+  doneSelections: "✔ Done (confirm selections)",
+  backQuestion: "← Back to previous question",
+  confirmPartialTitle: "Confirm partial submission?",
+  submitAnyway: "Submit anyway?",
+  validationFailed: "Validation failed: fix invalid fields",
+  requiredBadge: "*required",
+  optionalBadge: "optional",
+  markEmpty: "Explicit empty selection (mark blank)",
+  clearNote: "Clear note",
+  clearCustom: "Clear custom text",
+  togglePreview: "Toggle preview",
+  toggleOptions: "Toggle options",
+  submitConfirmTitle: "Submit questionnaire answers?",
+  scrollUpMore: "▲ (scroll up for more)",
+  scrollDownMore: "▼ (scroll down for more)",
+  previewFocusHint: "Press [p] to focus preview",
+  previewScrollHint: "[↑/↓/PgUp/PgDn] Scroll preview  [Esc/p] Return to controls",
+  previewCollapseHint: "Press [p] to collapse preview",
+};