@mrclrchtr/supi-ask-user 4.10.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,12 @@
1
+ import { AskUserParamsSchema } from "../../schema.ts";
2
+
3
+ export const ASK_USER_TOOL_NAME = "ask_user";
4
+ export const ASK_USER_TOOL_LABEL = "Ask User";
5
+
6
+ /** Canonical provider-facing metadata for the ask_user tool. */
7
+ export const askUserSpec = {
8
+ name: ASK_USER_TOOL_NAME,
9
+ label: ASK_USER_TOOL_LABEL,
10
+ parameters: AskUserParamsSchema,
11
+ executionMode: "sequential",
12
+ } as const;
@@ -12,6 +12,7 @@ import {
12
12
  import type { NormalizedChoiceQuestion } from "../types.ts";
13
13
  import { renderFormFrame } from "./form-render.ts";
14
14
  import { defaultChoiceRowIndex, type FormMode, focusForMode } from "./form-view.ts";
15
+ import { calculateFormHeightLimit } from "./form-viewport.ts";
15
16
  import type { FormArgs } from "./types.ts";
16
17
 
17
18
  type QuestionnaireMode = "choice" | "text" | "review";
@@ -44,8 +45,14 @@ export class AskUserForm implements Component, Focusable {
44
45
  private reviewFocusIndex = 0;
45
46
  private closed: boolean = false;
46
47
  private cachedWidth: number | undefined;
48
+ private cachedTerminalRows: number | undefined;
47
49
  private cachedEditorFocused: boolean | undefined;
48
50
  private cachedLines: string[] | undefined;
51
+ private scrollOffset = 0;
52
+ private viewportPageSize = 1;
53
+ private viewportMaxScrollOffset = 0;
54
+ private viewportOverflow = false;
55
+ private revealFocusedContent = true;
49
56
  private commentEdit: CommentEdit | undefined;
50
57
  private returnToReviewAfterEdit: boolean = false;
51
58
  private pendingEsc: boolean = false;
@@ -75,10 +82,15 @@ export class AskUserForm implements Component, Focusable {
75
82
  const mode = this.currentMode();
76
83
  const focus = focusForMode(mode);
77
84
  const editorFocused = this.focused && focus === "editor";
85
+ const terminalRows = this.args.tui.terminal.rows;
86
+ const dimensionsChanged =
87
+ this.cachedWidth !== undefined &&
88
+ (this.cachedWidth !== width || this.cachedTerminalRows !== terminalRows);
78
89
  if (isFocusable(this.editor)) this.editor.focused = editorFocused;
79
90
 
80
91
  if (
81
92
  this.cachedWidth === width &&
93
+ this.cachedTerminalRows === terminalRows &&
82
94
  this.cachedEditorFocused === editorFocused &&
83
95
  this.cachedLines
84
96
  ) {
@@ -86,9 +98,13 @@ export class AskUserForm implements Component, Focusable {
86
98
  }
87
99
 
88
100
  this.cachedWidth = width;
101
+ this.cachedTerminalRows = terminalRows;
89
102
  this.cachedEditorFocused = editorFocused;
90
- this.cachedLines = renderFormFrame({
103
+ const frame = renderFormFrame({
91
104
  width,
105
+ maxHeight: calculateFormHeightLimit(terminalRows),
106
+ scrollOffset: this.scrollOffset,
107
+ revealFocus: this.revealFocusedContent || dimensionsChanged,
92
108
  theme: this.args.theme,
93
109
  controller: this.args.controller,
94
110
  mode,
@@ -100,6 +116,12 @@ export class AskUserForm implements Component, Focusable {
100
116
  editorLabel: this.currentEditorLabel(),
101
117
  editorContext: this.commentEdit?.context,
102
118
  });
119
+ this.scrollOffset = frame.viewport.scrollOffset;
120
+ this.viewportPageSize = frame.viewport.pageSize;
121
+ this.viewportMaxScrollOffset = frame.viewport.maxScrollOffset;
122
+ this.viewportOverflow = frame.viewport.overflow;
123
+ this.revealFocusedContent = false;
124
+ this.cachedLines = frame.lines;
103
125
  return this.cachedLines;
104
126
  }
105
127
 
@@ -112,6 +134,7 @@ export class AskUserForm implements Component, Focusable {
112
134
  }
113
135
 
114
136
  if (this.handleEscapeKey(data)) return;
137
+ if (this.handleViewportKey(data)) return;
115
138
  if (this.handleNavigationKey(data)) return;
116
139
 
117
140
  if (this.isCommentEditorMode()) {
@@ -138,7 +161,7 @@ export class AskUserForm implements Component, Focusable {
138
161
 
139
162
  if (this.editorHandlesEscape && (this.baseMode === "text" || this.isCommentEditorMode())) {
140
163
  this.editor.handleInput(data);
141
- if (!this.closed) this.refresh();
164
+ if (!this.closed) this.refreshWithFocusReveal();
142
165
  return true;
143
166
  }
144
167
 
@@ -177,6 +200,19 @@ export class AskUserForm implements Component, Focusable {
177
200
  }
178
201
  }
179
202
 
203
+ private handleViewportKey(data: string): boolean {
204
+ if (!this.viewportOverflow) return false;
205
+ const editorFocused = focusForMode(this.currentMode()) === "editor";
206
+ const pageUp = editorFocused ? Key.alt("pageUp") : Key.pageUp;
207
+ const pageDown = editorFocused ? Key.alt("pageDown") : Key.pageDown;
208
+ const direction = matchesKey(data, pageUp) ? -1 : matchesKey(data, pageDown) ? 1 : 0;
209
+ if (direction === 0) return false;
210
+
211
+ const pageDelta = Math.max(1, this.viewportPageSize - 1);
212
+ this.scrollViewportByLines(direction * pageDelta);
213
+ return true;
214
+ }
215
+
180
216
  private handleNavigationKey(data: string): boolean {
181
217
  if (this.isCommentEditorMode()) return false;
182
218
 
@@ -251,14 +287,22 @@ export class AskUserForm implements Component, Focusable {
251
287
  }
252
288
 
253
289
  if (matchesKey(data, Key.up)) {
254
- this.reviewFocusIndex = Math.max(0, this.reviewFocusIndex - 1);
255
- this.refresh();
290
+ if (this.reviewFocusIndex === 0) {
291
+ this.scrollViewportByLines(-1);
292
+ return;
293
+ }
294
+ this.reviewFocusIndex -= 1;
295
+ this.refreshWithFocusReveal();
256
296
  return;
257
297
  }
258
298
 
259
299
  if (matchesKey(data, Key.down)) {
260
- this.reviewFocusIndex = Math.min(submitIndex, this.reviewFocusIndex + 1);
261
- this.refresh();
300
+ if (this.reviewFocusIndex === submitIndex) {
301
+ this.scrollViewportByLines(1);
302
+ return;
303
+ }
304
+ this.reviewFocusIndex += 1;
305
+ this.refreshWithFocusReveal();
262
306
  return;
263
307
  }
264
308
 
@@ -272,18 +316,7 @@ export class AskUserForm implements Component, Focusable {
272
316
  private handleChoiceKey(data: string): void {
273
317
  const question = this.args.controller.currentQuestion;
274
318
  if (question.type !== "choice") return;
275
-
276
- if (matchesKey(data, Key.up)) {
277
- this.choiceFocusIndex = Math.max(0, this.choiceFocusIndex - 1);
278
- this.refresh();
279
- return;
280
- }
281
-
282
- if (matchesKey(data, Key.down)) {
283
- this.choiceFocusIndex = Math.min(question.options.length - 1, this.choiceFocusIndex + 1);
284
- this.refresh();
285
- return;
286
- }
319
+ if (this.handleChoiceNavigation(data, question.options.length)) return;
287
320
 
288
321
  if (matchesKey(data, Key.space)) {
289
322
  if (question.multi) {
@@ -291,7 +324,7 @@ export class AskUserForm implements Component, Focusable {
291
324
  } else {
292
325
  this.args.controller.selectChoiceOption(question, this.choiceFocusIndex);
293
326
  }
294
- this.refresh();
327
+ this.refreshWithFocusReveal();
295
328
  return;
296
329
  }
297
330
 
@@ -305,7 +338,7 @@ export class AskUserForm implements Component, Focusable {
305
338
 
306
339
  if (data === "u") {
307
340
  this.args.controller.markCurrentQuestionUnanswered();
308
- this.refresh();
341
+ this.refreshWithFocusReveal();
309
342
  return;
310
343
  }
311
344
 
@@ -319,6 +352,28 @@ export class AskUserForm implements Component, Focusable {
319
352
  }
320
353
  }
321
354
 
355
+ private handleChoiceNavigation(data: string, optionCount: number): boolean {
356
+ if (matchesKey(data, Key.up)) {
357
+ if (this.choiceFocusIndex === 0) this.scrollViewportByLines(-1);
358
+ else {
359
+ this.choiceFocusIndex -= 1;
360
+ this.refreshWithFocusReveal();
361
+ }
362
+ return true;
363
+ }
364
+
365
+ if (matchesKey(data, Key.down)) {
366
+ if (this.choiceFocusIndex === optionCount - 1) this.scrollViewportByLines(1);
367
+ else {
368
+ this.choiceFocusIndex += 1;
369
+ this.refreshWithFocusReveal();
370
+ }
371
+ return true;
372
+ }
373
+
374
+ return false;
375
+ }
376
+
322
377
  // ── Text screen ─────────────────────────────────────────────────
323
378
 
324
379
  private handleTextKey(data: string): void {
@@ -327,7 +382,7 @@ export class AskUserForm implements Component, Focusable {
327
382
  if (data === "u") {
328
383
  this.args.controller.markCurrentQuestionUnanswered();
329
384
  this.setEditorText("");
330
- this.refresh();
385
+ this.refreshWithFocusReveal();
331
386
  return;
332
387
  }
333
388
  if (data === "c") {
@@ -346,10 +401,11 @@ export class AskUserForm implements Component, Focusable {
346
401
  if (matchesKey(data, Key.alt("u"))) {
347
402
  this.args.controller.markCurrentQuestionUnanswered();
348
403
  this.setEditorText("");
349
- this.refresh();
404
+ this.refreshWithFocusReveal();
350
405
  return;
351
406
  }
352
407
 
408
+ if (isFocusable(this.editor)) this.requestFocusReveal();
353
409
  this.editor.handleInput(data);
354
410
  this.refresh();
355
411
  }
@@ -357,6 +413,7 @@ export class AskUserForm implements Component, Focusable {
357
413
  // ── Comment editors ─────────────────────────────────────────────
358
414
 
359
415
  private handleCommentEditorKey(data: string): void {
416
+ if (isFocusable(this.editor)) this.requestFocusReveal();
360
417
  this.editor.handleInput(data);
361
418
  this.refresh();
362
419
  }
@@ -404,6 +461,7 @@ export class AskUserForm implements Component, Focusable {
404
461
  context: this.args.controller.questionnaire.title ?? "Form",
405
462
  };
406
463
  this.setEditorText(this.args.controller.comment ?? "");
464
+ this.resetViewport();
407
465
  this.refresh();
408
466
  }
409
467
 
@@ -415,6 +473,7 @@ export class AskUserForm implements Component, Focusable {
415
473
  returnChoiceFocusIndex: this.choiceFocusIndex,
416
474
  };
417
475
  this.setEditorText(this.args.controller.getQuestionComment(questionId) ?? "");
476
+ this.resetViewport();
418
477
  this.refresh();
419
478
  }
420
479
 
@@ -429,6 +488,7 @@ export class AskUserForm implements Component, Focusable {
429
488
  returnChoiceFocusIndex: optionIndex,
430
489
  };
431
490
  this.setEditorText(this.args.controller.getOptionComment(question.id, option.value) ?? "");
491
+ this.resetViewport();
432
492
  this.refresh();
433
493
  }
434
494
 
@@ -441,6 +501,7 @@ export class AskUserForm implements Component, Focusable {
441
501
  case "form":
442
502
  this.baseMode = "review";
443
503
  this.setEditorText("");
504
+ this.resetViewport();
444
505
  return;
445
506
  case "question":
446
507
  this.syncCurrentQuestion();
@@ -461,6 +522,7 @@ export class AskUserForm implements Component, Focusable {
461
522
  this.baseMode = "review";
462
523
  this.reviewFocusIndex = this.args.controller.questionnaire.questions.length;
463
524
  this.setEditorText("");
525
+ this.resetViewport();
464
526
  this.refresh();
465
527
  return;
466
528
  }
@@ -471,6 +533,7 @@ export class AskUserForm implements Component, Focusable {
471
533
  this.baseMode = "review";
472
534
  // Focus the Submit row by default so Enter submits immediately.
473
535
  this.reviewFocusIndex = this.args.controller.questionnaire.questions.length;
536
+ this.resetViewport();
474
537
  this.refresh();
475
538
  return;
476
539
  }
@@ -499,6 +562,7 @@ export class AskUserForm implements Component, Focusable {
499
562
  if (question.type === "text") {
500
563
  this.baseMode = "text";
501
564
  this.setEditorText(this.args.controller.getTextAnswer(question.id));
565
+ this.resetViewport();
502
566
  return;
503
567
  }
504
568
 
@@ -507,6 +571,7 @@ export class AskUserForm implements Component, Focusable {
507
571
  this.choiceFocusIndex =
508
572
  this.choiceFocusByQuestionId.get(question.id) ??
509
573
  defaultChoiceRowIndex(this.args.controller, question);
574
+ this.resetViewport();
510
575
  }
511
576
 
512
577
  private saveCurrentChoiceFocus(): void {
@@ -552,6 +617,32 @@ export class AskUserForm implements Component, Focusable {
552
617
  }
553
618
  }
554
619
 
620
+ private scrollViewportByLines(lines: number): void {
621
+ if (!this.viewportOverflow) return;
622
+ const nextOffset = Math.max(
623
+ 0,
624
+ Math.min(this.viewportMaxScrollOffset, this.scrollOffset + lines),
625
+ );
626
+ if (nextOffset === this.scrollOffset) return;
627
+ this.scrollOffset = nextOffset;
628
+ this.revealFocusedContent = false;
629
+ this.refresh();
630
+ }
631
+
632
+ private resetViewport(): void {
633
+ this.scrollOffset = 0;
634
+ this.revealFocusedContent = true;
635
+ }
636
+
637
+ private requestFocusReveal(): void {
638
+ this.revealFocusedContent = true;
639
+ }
640
+
641
+ private refreshWithFocusReveal(): void {
642
+ this.requestFocusReveal();
643
+ this.refresh();
644
+ }
645
+
555
646
  private finish(): void {
556
647
  if (this.closed) return;
557
648
  this.closed = true;
@@ -0,0 +1,173 @@
1
+ import type { Theme } from "@earendil-works/pi-coding-agent";
2
+ import { CURSOR_MARKER, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
3
+ import type { NormalizedChoiceQuestion } from "../types.ts";
4
+ import type { RenderFormFrameArgs } from "./form-render.ts";
5
+ import {
6
+ padRight,
7
+ pushWrappedWithPrefix,
8
+ renderMiniBox,
9
+ renderPrompt,
10
+ safeWidth,
11
+ } from "./form-render-primitives.ts";
12
+ import {
13
+ type FormLineRange,
14
+ offsetFormLineRange,
15
+ type RenderedFormSection,
16
+ } from "./form-viewport.ts";
17
+
18
+ export function renderChoiceScreen(args: RenderFormFrameArgs): RenderedFormSection {
19
+ const lines: string[] = [];
20
+ const question = args.controller.currentQuestion;
21
+
22
+ if (question.type !== "choice") return { lines };
23
+
24
+ lines.push(...renderPrompt(question.prompt, args.width));
25
+ if (args.controller.isQuestionMarkedUnanswered(question.id)) {
26
+ lines.push("");
27
+ lines.push(args.theme.fg("warning", "Marked unanswered; comments preserved."));
28
+ }
29
+ lines.push("");
30
+
31
+ if (args.detailsText && args.width >= 80) {
32
+ const section = renderChoiceWithDetails(args, question);
33
+ const focusedRange = offsetFormLineRange(section.focusedRange, lines.length);
34
+ lines.push(...section.lines);
35
+ return { lines, focusedRange };
36
+ }
37
+
38
+ let focusedRange: FormLineRange | undefined;
39
+ for (let i = 0; i < question.options.length; i += 1) {
40
+ const start = lines.length;
41
+ lines.push(...renderChoiceOptionLines(args, question, i, args.width));
42
+ if (i === args.choiceFocusIndex) focusedRange = { start, end: lines.length };
43
+ }
44
+
45
+ if (args.detailsText) {
46
+ lines.push("");
47
+ lines.push(...renderDetailsCard(args.theme, args.detailsText, args.width));
48
+ }
49
+
50
+ return { lines, focusedRange };
51
+ }
52
+
53
+ function renderChoiceWithDetails(
54
+ args: RenderFormFrameArgs,
55
+ question: NormalizedChoiceQuestion,
56
+ ): RenderedFormSection {
57
+ const gap = 2;
58
+ const divider = args.theme.fg("borderMuted", "│");
59
+ const dividerWidth = 1;
60
+ const minLeftWidth = 28;
61
+ const preferredDetailsWidth = Math.max(30, Math.floor(args.width * 0.38));
62
+ const rightWidth = Math.max(
63
+ 22,
64
+ Math.min(preferredDetailsWidth, args.width - gap - dividerWidth - gap - minLeftWidth),
65
+ );
66
+ const leftWidth = Math.max(1, args.width - gap - dividerWidth - gap - rightWidth);
67
+
68
+ const optionLines: string[] = [];
69
+ let focusedRange: FormLineRange | undefined;
70
+ for (let i = 0; i < question.options.length; i += 1) {
71
+ const start = optionLines.length;
72
+ optionLines.push(...renderChoiceOptionLines(args, question, i, leftWidth));
73
+ if (i === args.choiceFocusIndex) focusedRange = { start, end: optionLines.length };
74
+ }
75
+
76
+ const detailsLines = renderDetailsCard(args.theme, args.detailsText ?? "", rightWidth);
77
+ const merged: string[] = [];
78
+ const maxRows = Math.max(optionLines.length, detailsLines.length);
79
+ for (let i = 0; i < maxRows; i += 1) {
80
+ const left = optionLines[i] ?? "";
81
+ const right = detailsLines[i] ?? "";
82
+ const mergedLine = `${padRight(left, leftWidth)}${" ".repeat(gap)}${divider}${" ".repeat(gap)}${right}`;
83
+ merged.push(truncateToWidth(mergedLine, args.width));
84
+ }
85
+
86
+ return { lines: merged, focusedRange };
87
+ }
88
+
89
+ function renderChoiceOptionLines(
90
+ args: RenderFormFrameArgs,
91
+ question: NormalizedChoiceQuestion,
92
+ optionIndex: number,
93
+ width: number,
94
+ ): string[] {
95
+ const lines: string[] = [];
96
+ const opt = question.options[optionIndex];
97
+ const focused = optionIndex === args.choiceFocusIndex;
98
+ const selected = args.controller.isOptionSelected(question.id, opt.value);
99
+ const hasComment = !!args.controller.getOptionComment(question.id, opt.value);
100
+
101
+ const marker = choiceMarker(question.multi, selected);
102
+ const isRecommended = question.recommendedIndexes.includes(optionIndex);
103
+ const prefix = focused ? " → " : " ";
104
+ const label = `${marker} ${opt.label}${isRecommended ? " [recommended]" : ""}${hasComment ? " [comment]" : ""}`;
105
+ pushWrappedWithPrefix({
106
+ lines,
107
+ prefix,
108
+ text: focused ? args.theme.fg("accent", label) : label,
109
+ width,
110
+ });
111
+
112
+ if (opt.description) {
113
+ pushWrappedWithPrefix({
114
+ lines,
115
+ prefix: " ",
116
+ text: args.theme.fg("muted", opt.description),
117
+ width,
118
+ });
119
+ }
120
+
121
+ return lines;
122
+ }
123
+
124
+ function choiceMarker(multi: boolean, selected: boolean): string {
125
+ if (multi) return selected ? "[x]" : "[ ]";
126
+ return selected ? "(*)" : "( )";
127
+ }
128
+
129
+ export function renderTextScreen(args: RenderFormFrameArgs): RenderedFormSection {
130
+ const lines: string[] = [];
131
+ const question = args.controller.currentQuestion;
132
+
133
+ if (question.type !== "text") return { lines };
134
+
135
+ lines.push(...renderPrompt(question.prompt, args.width));
136
+ lines.push("");
137
+ lines.push(args.theme.fg("accent", "Your answer"));
138
+ const editorStart = lines.length;
139
+ const editorLines = args.editor.render(safeWidth(args.width));
140
+ lines.push(...editorLines);
141
+ const focusedRange = editorFocusRange(editorLines, editorStart);
142
+
143
+ if (question.placeholder && !args.editor.getText()) {
144
+ lines.push("");
145
+ lines.push(
146
+ ...wrapTextWithAnsi(args.theme.fg("dim", `Placeholder: ${question.placeholder}`), args.width),
147
+ );
148
+ }
149
+
150
+ return { lines, focusedRange };
151
+ }
152
+
153
+ export function renderEditorScreen(args: RenderFormFrameArgs): RenderedFormSection {
154
+ const lines: string[] = [];
155
+ const label = args.editorLabel ?? "Editor";
156
+ const title = args.editorContext ? `${label}: ${args.editorContext}` : label;
157
+ lines.push(args.theme.fg("accent", title));
158
+ const editorStart = lines.length;
159
+ const editorLines = args.editor.render(safeWidth(args.width));
160
+ lines.push(...editorLines);
161
+ return { lines, focusedRange: editorFocusRange(editorLines, editorStart) };
162
+ }
163
+
164
+ function editorFocusRange(editorLines: string[], start: number): FormLineRange {
165
+ const cursorLine = editorLines.findIndex((line) => line.includes(CURSOR_MARKER));
166
+ if (cursorLine >= 0) return { start: start + cursorLine, end: start + cursorLine + 1 };
167
+ return { start, end: start + 1 };
168
+ }
169
+
170
+ function renderDetailsCard(theme: Theme, detailsText: string, width: number): string[] {
171
+ const innerWidth = Math.max(1, safeWidth(width) - 4);
172
+ return renderMiniBox(theme, "Details", renderPrompt(detailsText, innerWidth), width);
173
+ }