vibecodingmachine-cli 2026.1.29-713 → 2026.2.20-426

package/src/utils/trui-quick-menu.js

@@ -0,0 +1,370 @@
+/**
+ * TRUI Quick Menu — raw-stdin keypress navigation engine
+ *
+ * Provides showQuickMenu(items, initialIndex) which renders a menu and listens
+ * for keypresses directly on stdin (no inquirer dependency).
+ *
+ * Item types:
+ *   'setting' — gray text; gets a letter shortcut; selectable
+ *   'action'  — white text; gets a letter shortcut; selectable
+ *   'info'    — gray text; NO letter; NOT selectable (display only)
+ *   'blank'   — empty separator line; not selectable
+ *
+ * Returns: Promise<{ value: string, selectedIndex: number }>
+ * Special value '__cancel__' is returned when ESC or left-arrow is pressed.
+ */
+
+const chalk = require('chalk');
+const readline = require('readline');
+const { debugLogger, perfMonitor, stateTracker, errorHandler } = require('./trui-debug');
+
+/**
+ * Convert a zero-based index to a letter shortcut (0→'a', 1→'b', …)
+ * @param {number} index
+ * @returns {string}
+ */
+function indexToLetter(index) {
+  return String.fromCharCode(97 + index);
+}
+
+/**
+ * Strip ANSI escape codes from a string for length calculation
+ */
+function stripAnsi(str) {
+  return str.replace(
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    ''
+  );
+}
+
+/**
+ * Calculate the number of terminal lines a piece of text occupies
+ * (accounts for line wrapping based on terminal column width)
+ */
+function getVisualLineCount(text) {
+  const columns = process.stdout.columns || 80;
+  let lineCount = 0;
+  for (const line of text.split('\n')) {
+    const len = stripAnsi(line).length;
+    lineCount += len === 0 ? 1 : Math.ceil(len / columns);
+  }
+  return lineCount;
+}
+
+/**
+ * Determine whether an item can receive keyboard focus
+ */
+function isSelectable(item) {
+  return item.type !== 'blank' && item.type !== 'info';
+}
+
+/**
+ * Build and display the menu; return the total number of visual lines printed
+ * so subsequent renders can reposition the cursor without clearing.
+ *
+ * @param {Array} items
+ * @param {number} selectedIndex
+ * @param {string} [hintText] - override the bottom hint line
+ * @returns {number} lines printed
+ */
+function renderMenu(items, selectedIndex, hintText) {
+  let linesPrinted = 0;
+  let letterIndex = 0;
+
+  items.forEach((item, index) => {
+    const isSelected = index === selectedIndex;
+    let output = '';
+
+    if (item.type === 'blank') {
+      process.stdout.write('\n');
+      linesPrinted += 1;
+      return;
+    }
+
+    if (item.type === 'info') {
+      output = chalk.gray(`  ${item.name}`);
+      process.stdout.write(output + '\n');
+      linesPrinted += getVisualLineCount(`  ${item.name}`);
+      return;
+    }
+
+    // 'header' type: no letter, but IS selectable (focusable with ↑↓, Enter returns value)
+    if (item.type === 'header') {
+      const raw = `${isSelected ? '❯ ' : '  '}${item.name}`;
+      if (isSelected) {
+        output = chalk.cyan(`❯ ${item.name}`);
+      } else {
+        output = chalk.gray(`  ${item.name}`);
+      }
+      process.stdout.write(output + '\n');
+      linesPrinted += getVisualLineCount(raw);
+      return;
+    }
+
+    // Assign letter — 'x' always = exit; everything else gets a→z in order
+    let letter;
+    if (item.value === 'exit') {
+      letter = 'x';
+    } else {
+      letter = indexToLetter(letterIndex);
+      letterIndex++;
+    }
+
+    const prefix = isSelected ? chalk.cyan('❯ ') : '  ';
+    const raw = `${isSelected ? '❯ ' : '  '}${letter}) ${item.name}`;
+
+    if (isSelected) {
+      output = chalk.cyan(`❯ ${letter}) ${item.name}`);
+    } else if (item.type === 'setting') {
+      output = chalk.gray(`  ${letter}) ${item.name}`);
+    } else {
+      output = `  ${letter}) ${item.name}`;
+    }
+
+    process.stdout.write(output + '\n');
+    linesPrinted += getVisualLineCount(raw);
+  });
+
+  // Help hint at the bottom
+  let helpText;
+  if (hintText !== undefined) {
+    helpText = `\n  ${hintText}`;
+  } else {
+    const letterCount = items.filter(
+      i => i.type !== 'blank' && i.type !== 'info' && i.value !== 'exit'
+    ).length;
+    const lastLetter = letterCount > 0 ? indexToLetter(letterCount - 1) : 'a';
+    const rangeText = letterCount > 1 ? `a-${lastLetter}` : letterCount === 1 ? 'a' : '';
+    helpText = `\n  [${rangeText ? rangeText + '  ' : ''}↑↓ navigate  ← back]`;
+  }
+  process.stdout.write(chalk.gray(helpText) + '\n');
+  linesPrinted += getVisualLineCount(helpText);
+
+  return linesPrinted;
+}
+
+// Debounce guard — shared between calls to prevent key-repeat re-entry
+let menuSuppressUntil = 0;
+
+/**
+ * Show a quick menu and wait for the user to select an item.
+ *
+ * @param {Array<{type: string, name: string, value: string}>} items
+ * @param {number} [initialSelectedIndex=0]
+ * @param {Object} [options={}]
+ * @param {Function} [options.extraKeys] - called for unhandled keys:
+ *   extraKeys(str, key, selectedIndex, { display, setSelectedIndex, resolveWith, items })
+ *   Return true to indicate the key was handled.
+ * @param {string} [options.hintText] - override the bottom hint line
+ * @returns {Promise<{value: string, selectedIndex: number}>}
+ */
+function showQuickMenu(items, initialSelectedIndex = 0, options = {}) {
+  const { extraKeys, hintText } = options;
+  try {
+    perfMonitor.start('showQuickMenu');
+    debugLogger.info('showQuickMenu called', { itemCount: items.length, initialSelectedIndex });
+
+    stateTracker.push({
+      type: 'menu',
+      items,
+      initialSelectedIndex,
+      startTime: Date.now()
+    });
+
+    return new Promise(resolve => {
+      // Find first selectable item at or after initialSelectedIndex
+      let selectedIndex = initialSelectedIndex;
+      while (selectedIndex < items.length && !isSelectable(items[selectedIndex])) {
+        selectedIndex++;
+      }
+      if (selectedIndex >= items.length) {
+        selectedIndex = items.findIndex(isSelectable);
+        if (selectedIndex === -1) selectedIndex = 0;
+      }
+
+      debugLogger.info('Initial selectedIndex set', { selectedIndex });
+      stateTracker.update({ selectedIndex });
+
+      let lastLinesPrinted = 0;
+      let isFirstRender = true;
+
+      const display = () => {
+        perfMonitor.start('render');
+        if (!isFirstRender) {
+          // Move cursor back up to start of menu and clear downward
+          readline.moveCursor(process.stdout, 0, -lastLinesPrinted);
+          readline.clearScreenDown(process.stdout);
+        }
+        lastLinesPrinted = renderMenu(items, selectedIndex, hintText);
+        isFirstRender = false;
+        perfMonitor.end('render');
+        debugLogger.info('Menu rendered', { linesPrinted: lastLinesPrinted, selectedIndex });
+      };
+
+      const cleanup = () => {
+        debugLogger.info('Cleaning up menu listeners');
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.removeListener('keypress', onKeypress);
+        process.stdin.pause();
+        perfMonitor.end('showQuickMenu');
+        stateTracker.pop();
+        debugLogger.info('Menu cleanup completed', perfMonitor.getMetrics());
+        // Reset debounce timer when cleaning up
+        menuSuppressUntil = 0;
+      };
+
+      const selectOption = index => {
+        debugLogger.info('Option selected', { index, value: items[index].value, name: items[index].name });
+        cleanup();
+        // Clear the selection indicator line
+        readline.moveCursor(process.stdout, 0, -(lastLinesPrinted - (index)));
+        readline.clearScreenDown(process.stdout);
+        process.stdout.write(chalk.cyan(`  → ${items[index].name}\n`));
+        menuSuppressUntil = Date.now() + 300;
+        resolve({ value: items[index].value, selectedIndex: index });
+      };
+
+      const onKeypress = (str, key) => {
+        stateTracker.update({ lastKeypress: { str, key } });
+        debugLogger.info('Keypress received', { str, key: key ? { name: key.name, ctrl: key.ctrl, shift: key.shift } : null });
+
+        if (!key) return;
+
+        // Always allow Ctrl+C
+        if (key.ctrl && key.name === 'c') {
+          cleanup();
+          process.exit(0);
+          return;
+        }
+
+        // Debounce
+        if (Date.now() < menuSuppressUntil) return;
+
+        // ESC → always cancel immediately
+        if (key.name === 'escape') {
+          cleanup();
+          menuSuppressUntil = Date.now() + 300;
+          resolve({ value: '__cancel__', selectedIndex });
+          return;
+        }
+
+        // Give caller first crack at keys (before letter shortcuts and left-arrow cancel)
+        if (extraKeys) {
+          const handled = extraKeys(str, key, selectedIndex, {
+            display,
+            setSelectedIndex: (i) => { selectedIndex = i; stateTracker.update({ selectedIndex }); },
+            resolveWith: (value) => { cleanup(); resolve({ value, selectedIndex }); },
+            items,
+          });
+          if (handled) return;
+        }
+
+        // Left-arrow → cancel (if extraKeys did not handle it)
+        if (key.name === 'left') {
+          cleanup();
+          menuSuppressUntil = Date.now() + 300;
+          resolve({ value: '__cancel__', selectedIndex });
+          return;
+        }
+
+        // Letter shortcuts
+        if (str && str.length === 1 && str >= 'a' && str <= 'z') {
+          if (str === 'x') {
+            // Find exit item
+            const exitIdx = items.findIndex(i => i.value === 'exit');
+            if (exitIdx !== -1) {
+              selectOption(exitIdx);
+            } else {
+              cleanup();
+              resolve({ value: 'exit', selectedIndex });
+            }
+            return;
+          }
+
+          if (str === 'f') {
+            // F key for feedback - global shortcut
+            cleanup();
+            resolve({ value: 'feedback', selectedIndex });
+            return;
+          }
+
+          const letterIdx = str.charCodeAt(0) - 97;
+          let count = 0;
+          for (let i = 0; i < items.length; i++) {
+            if (items[i].type !== 'blank' && items[i].type !== 'info' && items[i].value !== 'exit') {
+              if (count === letterIdx) {
+                selectOption(i);
+                return;
+              }
+              count++;
+            }
+          }
+          // Invalid letter - don't do anything, just return
+          return;
+        }
+
+        // Arrow up
+        if (key.name === 'up') {
+          let next = selectedIndex - 1;
+          while (next >= 0 && !isSelectable(items[next])) next--;
+          if (next < 0) {
+            // Wrap to bottom
+            next = items.length - 1;
+            while (next >= 0 && !isSelectable(items[next])) next--;
+          }
+          if (next >= 0 && next < items.length && isSelectable(items[next])) {
+            selectedIndex = next;
+            stateTracker.update({ selectedIndex });
+            display();
+          }
+          return;
+        }
+
+        // Arrow down
+        if (key.name === 'down') {
+          let next = selectedIndex + 1;
+          while (next < items.length && !isSelectable(items[next])) next++;
+          if (next >= items.length) {
+            // Wrap to top
+            next = 0;
+            while (next < items.length && !isSelectable(items[next])) next++;
+          }
+          if (next >= 0 && next < items.length && isSelectable(items[next])) {
+            selectedIndex = next;
+            stateTracker.update({ selectedIndex });
+            display();
+          }
+          return;
+        }
+
+        // Enter or right-arrow → select
+        if (key.name === 'return' || key.name === 'right') {
+          if (isSelectable(items[selectedIndex])) {
+            selectOption(selectedIndex);
+          }
+          return;
+        }
+      };
+
+      // Initial render
+      display();
+
+      // Set up keypress listener
+      readline.emitKeypressEvents(process.stdin);
+      if (process.stdin.isTTY && process.stdin.setRawMode) {
+        process.stdin.setRawMode(true);
+      }
+      // Shorter debounce (50ms) to prevent accidental double-presses while still being responsive
+      menuSuppressUntil = Date.now() + 50;
+      process.stdin.on('keypress', onKeypress);
+      process.stdin.resume();
+    });
+  } catch (error) {
+    debugLogger.error('showQuickMenu error', { error: error.message, stack: error.stack });
+    throw error;
+  }
+}
+
+module.exports = { showQuickMenu, indexToLetter, stripAnsi, getVisualLineCount };