@pi-archimedes/ask 2.0.0 → 2.1.0

package/README.md

@@ -2,27 +2,83 @@
 
 Structured question tool with tabbed multi-question flow and inline note editing.
 
+When language models need clarification, asking unstructured questions in text leads to guessing and back-and-forth ambiguity. This tool provides structured choice prompts, tabbed navigation for multi-part questions, and inline note editing so users can deliver clear, complete guidance in a single step.
+
+## What you get
+
+- **Tabbed multi-question flow** — submit review for multiple questions at once
+- **Single-question picker** — instant submit for quick decisions
+- **Inline note editing** — add custom notes and context per option
+- **Markdown context descriptions** — rich context descriptions rendered above options
+- **Automatic "Other" handling** — built-in custom response option with auto-focus
+- **Subagent support** — subagents can call `ask` and questions appear in the parent agent's TUI via bidirectional IPC
+
+## Screenshots
+
+![ask from a subagent](../../docs/images/ask-subagent.png)
+
 ## Install
 
 ```bash
-pi install @pi-archimedes/ask
+pi install npm:@pi-archimedes/ask
+```
+
+Or install full meta package:
+
+```bash
+pi install npm:pi-archimedes
 ```
 
-## Features
+## Usage
 
-- Tabbed multi-question flow with submit review
-- Single-question picker with instant submit
-- Inline note editing per option
-- Markdown context descriptions
-- Automatic "Other (type your own)" handling
-- Subagent support — subagents can call `ask` and the question appears in the parent's TUI (bidirectional IPC, no temp files)
+Single question example:
 
-![ask from a subagent](../../docs/images/ask-subagent.png)
+```jsonc
+{
+  "questions": [{
+    "id": "framework",
+    "question": "Which framework should we use?",
+    "options": [
+      { "label": "React" },
+      { "label": "Vue" },
+      { "label": "Svelte" }
+    ]
+  }]
+}
+```
+
+Multi-question with notes example:
 
-## Dependencies
+```jsonc
+{
+  "questions": [
+    {
+      "id": "priority",
+      "question": "What's the implementation priority?",
+      "description": "Choose the order for tackling these tasks.",
+      "options": [
+        { "label": "Core features first" },
+        { "label": "Tests first" },
+        { "label": "Design first" }
+      ],
+      "recommended": 0
+    },
+    {
+      "id": "approach",
+      "question": "Any additional constraints?",
+      "options": [
+        { "label": "No breaking changes" },
+        { "label": "Performance critical" },
+        { "label": "None" }
+      ],
+      "multi": true
+    }
+  ]
+}
+```
 
-Depends on [`@pi-archimedes/core`](../core) for the shared event bus used to relay subagent questions.
+## Integration
 
-## Settings
+Depends on [`@pi-archimedes/core`](../core) for the shared event bus used to relay subagent questions. Subagents call `ask` and questions are safely dispatched to the parent agent's TUI over bidirectional IPC with no temporary files.
 
-No settings yet.
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/ask",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.0.0"
+    "@pi-archimedes/core": "2.1.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/cursor.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest";
+import * as fc from "fast-check";
+import { getLinearCursorIndexFromEditor } from "./cursor.js";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+interface MockEditor {
+  lines: string[];
+  cursorLine: number;
+  cursorCol: number;
+}
+
+function makeEditor(lines: string[], cursorLine: number, cursorCol: number): MockEditor {
+  return { lines, cursorLine, cursorCol };
+}
+
+function editorFromMock(m: MockEditor) {
+  return {
+    getLines: () => m.lines,
+    getCursor: () => ({ line: m.cursorLine, col: m.cursorCol }),
+  };
+}
+
+// ── getLinearCursorIndexFromEditor ──────────────────────────────────────────
+
+describe("getLinearCursorIndexFromEditor", () => {
+  it("single line, cursor at start → 0", () => {
+    const editor = editorFromMock(makeEditor(["hello"], 0, 0));
+    expect(getLinearCursorIndexFromEditor(editor)).toBe(0);
+  });
+
+  it("single line, cursor at end → line length", () => {
+    const editor = editorFromMock(makeEditor(["hello"], 0, 5));
+    expect(getLinearCursorIndexFromEditor(editor)).toBe(5);
+  });
+
+  it("multi-line, cursor on second line → first line length + 1 + col", () => {
+    const editor = editorFromMock(makeEditor(["hello", "world"], 1, 3));
+    // "hello" (5 chars) + "\n" (1 char) + 3 cols into "world" = 9
+    expect(getLinearCursorIndexFromEditor(editor)).toBe(9);
+  });
+
+  it("empty editor → 0", () => {
+    const editor = editorFromMock(makeEditor([], 0, 0));
+    expect(getLinearCursorIndexFromEditor(editor)).toBe(0);
+  });
+
+  it("cursor beyond bounds clamped correctly", () => {
+    const editor = editorFromMock(makeEditor(["hi"], 10, 100));
+    // Clamped to last line (line 0) and end of line (col 2)
+    expect(getLinearCursorIndexFromEditor(editor)).toBe(2);
+  });
+
+  it("property: linear index always >= 0", () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.string({ maxLength: 50 }), { maxLength: 20 }),
+        fc.nat({ max: 100 }),
+        fc.nat({ max: 100 }),
+        (lines, cursorLine, cursorCol) => {
+          const editor = editorFromMock(makeEditor(lines, cursorLine, cursorCol));
+          const result = getLinearCursorIndexFromEditor(editor);
+          if (result < 0) {
+            throw new Error(`Linear index is negative: ${result}`);
+          }
+        },
+      ),
+      { verbose: false },
+    );
+  });
+
+  it("property: linear index <= total character count", () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.string({ maxLength: 50 }), { maxLength: 20 }),
+        fc.nat({ max: 100 }),
+        fc.nat({ max: 100 }),
+        (lines, cursorLine, cursorCol) => {
+          const editor = editorFromMock(makeEditor(lines, cursorLine, cursorCol));
+          const result = getLinearCursorIndexFromEditor(editor);
+          const totalChars = lines.reduce((sum, line, i) => sum + line.length + (i < lines.length - 1 ? 1 : 0), 0);
+          if (result > totalChars) {
+            throw new Error(`Linear index ${result} exceeds total chars ${totalChars}`);
+          }
+        },
+      ),
+      { verbose: false },
+    );
+  });
+});

package/src/wrap.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as fc from "fast-check";
+
+// ── Mock @earendil-works/pi-tui ────────────────────────────────────────────
+
+vi.mock("@earendil-works/pi-tui", () => ({
+  wrapTextWithAnsi: vi.fn(),
+  truncateToWidth: vi.fn(),
+}));
+
+// Lazy import after mock is set up
+const { wrapTextWithAnsi, truncateToWidth } = await import("@earendil-works/pi-tui");
+
+const { appendWrappedTextLines } = await import("./wrap.js");
+
+describe("appendWrappedTextLines", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // Default: wrapTextWithAnsi returns input as single line (no wrapping needed)
+    vi.mocked(wrapTextWithAnsi).mockImplementation((text: string) => [text]);
+
+    // Default: truncateToWidth returns input unchanged (no truncation needed)
+    vi.mocked(truncateToWidth).mockImplementation((text: string) => text);
+  });
+
+  it("single line within width → no wrapping", () => {
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "hello", 80);
+    expect(rendered).toEqual(["hello"]);
+    expect(wrapTextWithAnsi).toHaveBeenCalledWith("hello", 80);
+  });
+
+  it("long line → wrapped to specified width", () => {
+    vi.mocked(wrapTextWithAnsi).mockReturnValueOnce(["part1", "part2", "part3"]);
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "a very long line of text that needs wrapping", 10);
+    expect(rendered).toEqual(["part1", "part2", "part3"]);
+    expect(wrapTextWithAnsi).toHaveBeenCalledWith("a very long line of text that needs wrapping", 10);
+  });
+
+  it("multiline input → each line wrapped independently", () => {
+    vi.mocked(wrapTextWithAnsi).mockImplementation((text: string) => {
+      if (text === "line1") return ["line1"];
+      if (text === "line2") return ["line2"];
+      return [text];
+    });
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "line1\nline2", 80);
+    expect(rendered).toEqual(["line1", "line2"]);
+    expect(wrapTextWithAnsi).toHaveBeenCalledTimes(2);
+    expect(wrapTextWithAnsi).toHaveBeenNthCalledWith(1, "line1", 80);
+    expect(wrapTextWithAnsi).toHaveBeenNthCalledWith(2, "line2", 80);
+  });
+
+  it("indent reduces effective wrap width", () => {
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "hello", 80, { indent: 4 });
+    expect(wrapTextWithAnsi).toHaveBeenCalledWith("hello", 76);
+    expect(truncateToWidth).toHaveBeenCalledWith("    hello", 80);
+  });
+
+  it("formatLine applied to each wrapped line", () => {
+    vi.mocked(wrapTextWithAnsi).mockReturnValueOnce(["part1", "part2"]);
+    const formatLine = vi.fn((line: string) => `>>${line}<<`);
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "some text", 80, { formatLine });
+    expect(formatLine).toHaveBeenCalledWith("part1");
+    expect(formatLine).toHaveBeenCalledWith("part2");
+    expect(truncateToWidth).toHaveBeenCalledWith(">>part1<<", 80);
+    expect(truncateToWidth).toHaveBeenCalledWith(">>part2<<", 80);
+  });
+
+  it("empty text → single empty line added", () => {
+    const rendered: string[] = [];
+    appendWrappedTextLines(rendered, "", 80);
+    expect(rendered).toEqual([""]);
+  });
+
+  it("property: output lines never exceed safeWidth chars", () => {
+    fc.assert(
+      fc.property(
+        fc.string({ maxLength: 200 }),
+        fc.integer({ min: 1, max: 80 }),
+        fc.integer({ min: 0, max: 20 }),
+        (text, width, indent) => {
+          const safeWidth = Math.max(1, Math.floor(width));
+          const actualIndent = Math.max(0, Math.floor(indent));
+          const wrapWidth = Math.max(1, safeWidth - actualIndent);
+
+          // Mock: wrap returns single line (worst case for truncation)
+          vi.mocked(wrapTextWithAnsi).mockReturnValueOnce([text]);
+          // Mock: truncateToWidth truncates to safeWidth
+          vi.mocked(truncateToWidth).mockImplementation((s: string) => s.slice(0, safeWidth));
+
+          const rendered: string[] = [];
+          appendWrappedTextLines(rendered, text, safeWidth, { indent: actualIndent });
+
+          for (const line of rendered) {
+            if (line.length > safeWidth) {
+              throw new Error(`Line length ${line.length} exceeds safeWidth ${safeWidth}`);
+            }
+          }
+        },
+      ),
+      { verbose: false },
+    );
+  });
+});