@hheei/pi-ask-user 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Enzo Lucchesi
+Copyright (c) 2026 hheei
+
+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,69 @@
-# Temporary Holding Version
+# @hheei/pi-ask-user
 
-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 `ask_user` tool for pi: one focused question, or 2-4 independent questions in one prompt, with multiple choice, multi-select, and freeform answers.
+
+Forked from [`edlsh/pi-ask-user`](https://github.com/edlsh/pi-ask-user) at revision `df1df70` (v0.17.1). Upstream is MIT licensed; see [LICENSE](./LICENSE).
+
+## What the fork changes
+
+- Ships compiled `dist/` through `tsc` instead of raw TypeScript, matching the other `@hheei/pi-*` packages.
+- Uses the `typebox` package instead of `@sinclair/typebox`.
+- Tests run on vitest instead of `bun test`.
+- Code conforms to this repo's Biome and `exactOptionalPropertyTypes` rules.
+- Reads preferences through `@hheei/pi-ext-core` from the `askUser` section of `ext_settings.json`, so project `.pi/ext_settings.json` can override the global file. Upstream's own `ask-user.json` and the `PI_ASK_USER_*` environment layer are gone.
+- Drops upstream's searchable split-pane list, optional comment stage, overlay hide shortcut, review-page scrolling, and `ctrl+j`/`ctrl+k` vim aliases: the prompt now matches pi's own select-list keys.
+- Drops the upstream `pi-tern` native-presentation integration. Prompts render through pi's own TUI components, and results publish presentation facts that `@hheei/pi-ext-ui` frames with its 0/1/2 fold levels when it is installed.
+- Registers an `ask_user` settings page through `@hheei/pi-ext-core`, so the preferences below are editable in the host settings UI instead of by hand.
+
+Module boundaries, invariants, and the test layout are recorded in
+[`docs/architecture/ask-user.md`](../../docs/architecture/ask-user.md).
+
+The batch contract is unchanged: `context`, `options`, `allowMultiple`, and `allowFreeform` belong on each `questions` entry, never at the top level. Top-level copies are ignored rather than rejected, because strict providers fill every declared property with an empty default. A one-entry `questions` array is unwrapped and asked as a single question instead of failing.
+
+## Install
+
+```bash
+pi install npm:@hheei/pi-ask-user
+```
+
+## Tool
+
+| Parameter | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `question` | `string?` | — | The question. With `questions`, it is only the batch heading |
+| `questions` | `{question, context?, options?, allowMultiple?, allowFreeform?}[]?` | — | 2-4 independent questions, used instead of `question` |
+| `context` | `string?` | — | Summary shown above the question |
+| `options` | `{title, description?}[]?` | — | Choices offered to the user |
+| `allowMultiple` | `boolean?` | `false` | Allow selecting several options |
+| `allowFreeform` | `boolean?` | `true` | Add a freeform answer row |
+| `displayMode` | `"overlay" \| "inline"` | `overlay` | Centered modal or in-place prompt |
+| `timeout_ms` | `integer?` | — | Auto-dismiss after N milliseconds; the result is cancelled |
+
+## Keys
+
+| Context | Keys |
+| --- | --- |
+| List | `↑`/`↓`, `tab`/`shift+tab`, `1`-`9` jump or toggle |
+| Single select | `enter` choose (on the freeform row: open the editor) |
+| Multi select | `space` tick, `enter` submit |
+| Editor | `enter` submit, `shift+enter`/`ctrl+j` newline, `esc` back or cancel |
+| Prompt | `ctrl+e` expand context, `PgUp`/`PgDn`/`Home`/`End` scroll (overlay) |
+| Batch | `tab`/`shift+tab` pages, `1`-`N` jump from review, `enter` submit, `esc` cancel |
+| Anywhere | `esc`/`ctrl+c` cancel |
+
+## Preferences
+
+One setting, editable from the host settings UI or by hand: `displayMode` in the `askUser` section of `<agent-dir>/ext_settings.json` (project `.pi/ext_settings.json` wins), read on every call. A call parameter overrides it.
+
+`ask:answered` and `ask:cancelled` events carry only the question and the response kind; context and the actual answer stay in the tool result.
+
+## Skill
+
+The package bundles the `ask-user` skill, which turns `ask_user` into a gate before high-stakes or ambiguous decisions. It is installed with the package; remove `skills/` from your package list if you only want the tool.
+
+## Development
+
+```bash
+pnpm --filter @hheei/pi-ask-user run build
+pnpm exec vitest run packages/pi-ask-user/test
+```

package/dist/ask-prompt.d.ts

@@ -0,0 +1,60 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, type KeybindingsManager, type TUI } from "@earendil-works/pi-tui";
+import type { PromptSettings } from "./preferences";
+import { type AskUIResult } from "./response";
+import type { BatchQuestion } from "./schema";
+/**
+ * Interactive ask UI. Uses a root Container for layout and swaps the center
+ * component between the option list and an Editor (freeform mode).
+ */
+export declare class AskComponent extends Container {
+    private readonly prompt;
+    private readonly settings;
+    private readonly contextPane;
+    private readonly tui;
+    private readonly theme;
+    private readonly keybindings;
+    private readonly onDone;
+    private mode;
+    private chrome;
+    private freeformDraft;
+    private promptScrollOffset;
+    private promptMaxScrollOffset;
+    private promptViewportRows;
+    private get contextIsCollapsible();
+    private get contextExpanded();
+    private questionText;
+    private modeContainer;
+    private optionListValue?;
+    private editor?;
+    private _focused;
+    get focused(): boolean;
+    set focused(value: boolean);
+    constructor(prompt: BatchQuestion, settings: PromptSettings, tui: TUI, theme: Theme, keybindings: KeybindingsManager, onDone: (result: AskUIResult | null) => void);
+    invalidate(): void;
+    render(width: number): string[];
+    private renderInlineLayout;
+    private renderOverlayLayout;
+    private buildPromptLines;
+    private renderModeLines;
+    private renderEditorModeLines;
+    /** Header shared by the container children (inline) and the overlay budget path. */
+    private editorHeader;
+    private renderPromptPane;
+    private updateStaticText;
+    /** Batch pages: show the question strip and the page-navigation hint above the question. */
+    setBatchChrome(frameTitle: string, navigationHint: string): void;
+    /** The hint row for the current mode; `promptScrollable` only applies where the pane can clip. */
+    private helpLines;
+    /** The select-mode body; both lists share the wiring and differ in the selection shape. */
+    private get optionList();
+    private ensureEditor;
+    private saveEditorDraft;
+    private showSelectMode;
+    private showEditorMode;
+    private toggleContext;
+    private setPromptScrollOffset;
+    private handlePromptScrollInput;
+    private scrollPromptBy;
+    handleInput(data: string): void;
+}

package/dist/ask-prompt.js

@@ -0,0 +1,360 @@
+import { Container, Editor, Key, matchesKey, Spacer, Text, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
+import { INLINE_CONTEXT_MAX_ROWS } from "./constants";
+import { MultiSelectList } from "./multi-select-list";
+import { PromptContextPane } from "./prompt-context";
+import { buildHelpText } from "./prompt-help";
+import { contextShouldCollapse, getOverlayMaxRenderLinesForRows, planOverlayBody, RAIL_ROWS, railRow, } from "./prompt-layout";
+import { applyOverflowMarkers, limitEditorLines, limitLines } from "./prompt-overflow";
+import { createFreeformResponse, createSelectionResponse } from "./response";
+import { pageDelta } from "./shortcuts";
+import { WrappedSingleSelectList } from "./single-select-list";
+function editorTheme(theme) {
+    return {
+        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),
+        },
+    };
+}
+/**
+ * Interactive ask UI. Uses a root Container for layout and swaps the center
+ * component between the option list and an Editor (freeform mode).
+ */
+export class AskComponent extends Container {
+    prompt;
+    settings;
+    contextPane;
+    tui;
+    theme;
+    keybindings;
+    onDone;
+    mode = "select";
+    chrome = "";
+    freeformDraft = "";
+    promptScrollOffset = 0;
+    promptMaxScrollOffset = 0;
+    promptViewportRows = 0;
+    get contextIsCollapsible() {
+        return this.contextPane.collapsible;
+    }
+    get contextExpanded() {
+        return this.contextPane.expanded;
+    }
+    // Static layout components
+    questionText;
+    modeContainer;
+    // Mode components
+    optionListValue;
+    editor;
+    // Focusable - propagate to Editor for IME cursor positioning
+    _focused = false;
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        this._focused = value;
+        if (this.editor && this.mode === "freeform") {
+            this.editor.focused = value;
+        }
+    }
+    constructor(prompt, settings, tui, theme, keybindings, onDone) {
+        super();
+        this.prompt = prompt;
+        this.settings = settings;
+        this.tui = tui;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.onDone = onDone;
+        this.questionText = new Text("", 1, 0);
+        this.addChild(this.questionText);
+        this.contextPane = new PromptContextPane(prompt.context, theme, () => this.invalidate());
+        if (this.contextPane.component) {
+            this.addChild(new Spacer(1));
+            this.addChild(this.contextPane.component);
+        }
+        this.addChild(new Spacer(1));
+        this.modeContainer = new Container();
+        this.addChild(this.modeContainer);
+        this.updateStaticText();
+        // A question without options opens straight in the editor, like the
+        // input dialog a single question without options uses.
+        if (this.prompt.options.length === 0) {
+            this.showEditorMode();
+        }
+        else {
+            this.showSelectMode();
+        }
+    }
+    invalidate() {
+        super.invalidate();
+        this.updateStaticText();
+    }
+    render(width) {
+        if (this.settings.displayMode === "overlay")
+            return this.renderOverlayLayout(width);
+        if (this.mode === "select")
+            this.optionList.setMaxVisibleRows(12);
+        return this.renderInlineLayout(width);
+    }
+    renderInlineLayout(width) {
+        const fullContextLines = this.contextPane.fullLines(width);
+        this.contextPane.setCollapsible(fullContextLines.length > INLINE_CONTEXT_MAX_ROWS);
+        return [
+            railRow(this.theme, width),
+            ...this.buildPromptLines(width, fullContextLines),
+            "",
+            ...this.modeContainer.render(width),
+            railRow(this.theme, width),
+            ...this.helpLines(width, false),
+        ];
+    }
+    renderOverlayLayout(width) {
+        const maxLines = getOverlayMaxRenderLinesForRows(this.tui.terminal.rows);
+        if (maxLines <= 0)
+            return [];
+        const bodyCapacity = Math.max(0, maxLines - RAIL_ROWS);
+        let helpLines = this.helpLines(width, false);
+        const questionLines = this.questionText.render(width);
+        const fullContextLines = this.contextPane.fullLines(width);
+        this.contextPane.setCollapsible(contextShouldCollapse({
+            displayMode: this.settings.displayMode,
+            mode: this.mode,
+            contextCollapsible: this.contextIsCollapsible,
+            questionRows: questionLines.length,
+            contextRows: fullContextLines.length,
+            bodyCapacity,
+            helpRows: helpLines.length,
+        }));
+        const promptLines = this.buildPromptLines(width, fullContextLines);
+        const plan = planOverlayBody({
+            maxRenderLines: bodyCapacity,
+            mode: this.mode,
+            contextCollapsible: this.contextIsCollapsible,
+            promptRows: promptLines.length,
+            helpRows: helpLines.length,
+        });
+        const modeLines = this.renderModeLines(width, plan.modeBudget);
+        const promptBudget = plan.promptBudget + Math.max(0, plan.modeBudget - modeLines.length);
+        const promptPaneLines = this.renderPromptPane(promptLines, promptBudget, width);
+        helpLines = this.helpLines(width, promptLines.length > promptBudget);
+        const visibleHelpLines = limitLines(this.theme, helpLines, plan.helpBudget, width, false);
+        const contentLines = [
+            ...promptPaneLines,
+            ...(plan.separatorRows > 0 && promptPaneLines.length > 0 && modeLines.length > 0 ? [""] : []),
+            ...modeLines,
+        ];
+        return [
+            railRow(this.theme, width),
+            ...contentLines.slice(0, plan.bodyCapacity),
+            railRow(this.theme, width),
+            ...visibleHelpLines,
+        ].slice(0, maxLines);
+    }
+    buildPromptLines(width, fullContextLines) {
+        const questionLines = this.questionText.render(width);
+        const contextLines = this.contextPane.displayLines(fullContextLines, width);
+        const contextSeparator = this.contextIsCollapsible && !this.contextExpanded ? [] : [""];
+        return [
+            ...questionLines,
+            ...(contextLines.length > 0 ? [...contextSeparator, ...contextLines] : []),
+        ];
+    }
+    renderModeLines(width, budget) {
+        const safeBudget = Math.max(0, Math.floor(budget));
+        if (safeBudget <= 0)
+            return [];
+        if (this.mode === "select") {
+            this.optionList.setMaxVisibleRows(Math.max(1, safeBudget));
+            return limitLines(this.theme, this.modeContainer.render(width), safeBudget, width, true);
+        }
+        return this.renderEditorModeLines(width, safeBudget);
+    }
+    renderEditorModeLines(width, budget) {
+        const headerLines = [...new Text(this.editorHeader(), 1, 0).render(width), ""];
+        const minimumEditorRows = Math.min(3, budget);
+        const headerBudget = Math.max(0, budget - minimumEditorRows);
+        const visibleHeaderLines = limitLines(this.theme, headerLines, headerBudget, width, true);
+        const editorBudget = Math.max(0, budget - visibleHeaderLines.length);
+        return [
+            ...visibleHeaderLines,
+            ...limitEditorLines(this.theme, this.ensureEditor().render(width), editorBudget, width),
+        ];
+    }
+    /** Header shared by the container children (inline) and the overlay budget path. */
+    editorHeader() {
+        return this.theme.fg("accent", this.theme.bold("Custom response"));
+    }
+    renderPromptPane(promptLines, budget, width) {
+        const viewportRows = Math.max(0, Math.floor(budget));
+        this.promptViewportRows = viewportRows;
+        if (viewportRows <= 0 || promptLines.length === 0) {
+            this.promptMaxScrollOffset = 0;
+            this.promptScrollOffset = 0;
+            return [];
+        }
+        this.promptMaxScrollOffset = Math.max(0, promptLines.length - viewportRows);
+        this.promptScrollOffset = Math.max(0, Math.min(this.promptScrollOffset, this.promptMaxScrollOffset));
+        const visibleLines = promptLines.slice(this.promptScrollOffset, this.promptScrollOffset + viewportRows);
+        const hasHiddenAbove = this.promptScrollOffset > 0;
+        const hasHiddenBelow = this.promptScrollOffset + viewportRows < promptLines.length;
+        return applyOverflowMarkers(this.theme, visibleLines, width, hasHiddenAbove, hasHiddenBelow);
+    }
+    updateStaticText() {
+        const theme = this.theme;
+        const question = theme.fg("text", theme.bold(this.prompt.question));
+        this.questionText.setText(this.chrome ? `${this.chrome}\n${question}` : question);
+        this.contextPane.updateText();
+    }
+    /** Batch pages: show the question strip and the page-navigation hint above the question. */
+    setBatchChrome(frameTitle, navigationHint) {
+        const theme = this.theme;
+        this.chrome = `${theme.fg("dim", frameTitle)}  ${theme.fg("dim", navigationHint)}`;
+        this.updateStaticText();
+    }
+    /** The hint row for the current mode; `promptScrollable` only applies where the pane can clip. */
+    helpLines(width, promptScrollable) {
+        return wrapTextWithAnsi(buildHelpText({
+            theme: this.theme,
+            mode: this.mode,
+            displayMode: this.settings.displayMode,
+            allowMultiple: this.prompt.allowMultiple,
+            hasOptions: this.prompt.options.length > 0,
+            contextCollapsible: this.contextIsCollapsible,
+            contextToggleKey: this.contextPane.toggleKey(),
+            promptScrollable,
+            keybindings: this.keybindings,
+        }), width);
+    }
+    /** The select-mode body; both lists share the wiring and differ in the selection shape. */
+    get optionList() {
+        if (this.optionListValue)
+            return this.optionListValue;
+        if (this.prompt.allowMultiple) {
+            const list = new MultiSelectList(this.prompt.options, this.prompt.allowFreeform, this.theme, this.keybindings);
+            list.onSubmit = (result) => this.onDone(createSelectionResponse(result));
+            this.optionListValue = list;
+        }
+        else {
+            const list = new WrappedSingleSelectList(this.prompt.options, this.prompt.allowFreeform, this.theme, this.keybindings);
+            list.onSubmit = (result) => this.onDone(createSelectionResponse([result]));
+            this.optionListValue = list;
+        }
+        this.optionListValue.onCancel = () => this.onDone(null);
+        this.optionListValue.onEnterFreeform = () => this.showEditorMode();
+        return this.optionListValue;
+    }
+    ensureEditor() {
+        if (this.editor)
+            return this.editor;
+        const editor = new Editor(this.tui, editorTheme(this.theme));
+        editor.disableSubmit = false;
+        editor.onSubmit = (text) => {
+            this.onDone(createFreeformResponse(text));
+        };
+        this.editor = editor;
+        return editor;
+    }
+    saveEditorDraft() {
+        if (!this.editor)
+            return;
+        this.freeformDraft = this.editor.getText();
+    }
+    showSelectMode() {
+        if (this.mode === "freeform")
+            this.saveEditorDraft();
+        this.mode = "select";
+        this.modeContainer.clear();
+        this.modeContainer.addChild(this.optionList);
+        this.invalidate();
+        this.tui.requestRender();
+    }
+    showEditorMode() {
+        if (this.mode === "freeform")
+            this.saveEditorDraft();
+        this.mode = "freeform";
+        this.modeContainer.clear();
+        const editor = this.ensureEditor();
+        editor.setText(this.freeformDraft);
+        editor.focused = this._focused;
+        this.modeContainer.addChild(new Text(this.editorHeader(), 1, 0));
+        this.modeContainer.addChild(new Spacer(1));
+        this.modeContainer.addChild(editor);
+        this.invalidate();
+        this.tui.requestRender();
+    }
+    toggleContext() {
+        if (this.mode !== "select")
+            return false;
+        if (!this.contextPane.toggle())
+            return false;
+        this.promptScrollOffset = 0;
+        this.invalidate();
+        this.tui.requestRender();
+        return true;
+    }
+    setPromptScrollOffset(nextOffset) {
+        this.promptScrollOffset = Math.max(0, Math.min(Math.floor(nextOffset), this.promptMaxScrollOffset));
+    }
+    handlePromptScrollInput(data) {
+        if (this.settings.displayMode !== "overlay")
+            return false;
+        if (this.promptMaxScrollOffset <= 0)
+            return false;
+        // Prompt scrolling is select-mode only: in freeform mode the editor owns
+        // PageUp/PageDown (tui.editor.pageUp/pageDown) for paging through long
+        // input, so intercepting them here would steal editor keys.
+        if (this.mode !== "select")
+            return false;
+        const pageRows = Math.max(1, this.promptViewportRows - 1);
+        const halfPageRows = Math.max(1, Math.floor(this.promptViewportRows / 2));
+        const delta = pageDelta(data, pageRows);
+        if (delta !== 0)
+            return this.scrollPromptBy(delta);
+        if (matchesKey(data, Key.home))
+            return this.scrollPromptBy(-this.promptScrollOffset);
+        if (matchesKey(data, Key.end))
+            return this.scrollPromptBy(this.promptMaxScrollOffset);
+        if (matchesKey(data, Key.ctrl("u")))
+            return this.scrollPromptBy(-halfPageRows);
+        if (matchesKey(data, Key.ctrl("d")))
+            return this.scrollPromptBy(halfPageRows);
+        return false;
+    }
+    scrollPromptBy(delta) {
+        this.setPromptScrollOffset(this.promptScrollOffset + delta);
+        return true;
+    }
+    handleInput(data) {
+        if (matchesKey(data, this.contextPane.toggleKey()) && this.toggleContext()) {
+            return;
+        }
+        if (this.handlePromptScrollInput(data)) {
+            this.tui.requestRender();
+            return;
+        }
+        if (this.mode === "freeform") {
+            if (matchesKey(data, Key.escape)) {
+                // Without options there is no list to go back to, so esc cancels.
+                if (this.prompt.options.length === 0) {
+                    this.onDone(null);
+                    return;
+                }
+                this.showSelectMode();
+                return;
+            }
+            if (this.keybindings.matches(data, "tui.select.cancel")) {
+                this.onDone(null);
+                return;
+            }
+            this.ensureEditor().handleInput(data);
+            this.tui.requestRender();
+            return;
+        }
+        this.optionList.handleInput(data);
+        this.tui.requestRender();
+    }
+}

package/dist/batch-prompt.d.ts

@@ -0,0 +1,42 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, type KeybindingsManager, type TUI } from "@earendil-works/pi-tui";
+import type { PromptSettings } from "./preferences";
+import { type BatchAnswer } from "./response";
+import type { BatchQuestion } from "./schema";
+/**
+ * One prompt for a whole `questions` batch: a page per question plus a review
+ * page. Each page is an AskComponent that stays alive, so drafts and checkboxes
+ * survive moving between pages. Answers are recorded per page and only the
+ * review page submits; esc that would cancel a page cancels the batch.
+ */
+export declare class BatchAskComponent implements Component {
+    private questions;
+    private settings;
+    private tui;
+    private theme;
+    private keybindings;
+    private onDone;
+    private heading?;
+    private pages;
+    private answers;
+    private current;
+    private title;
+    private confirmingSkips;
+    private _focused;
+    constructor(questions: BatchQuestion[], settings: PromptSettings, tui: TUI, theme: Theme, keybindings: KeybindingsManager, onDone: (answers: BatchAnswer[] | null) => void, heading?: string | undefined);
+    get focused(): boolean;
+    set focused(value: boolean);
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    private handlePageDone;
+    private goTo;
+    private updateChrome;
+    /** Submit from the review page; with unanswered questions, the first submit asks to confirm. */
+    private submitReview;
+    private unansweredCount;
+    private handleReviewInput;
+    private renderReview;
+    /** Rows the review page may use, rails included. */
+    private reviewLineCap;
+}