pyre-cli 10.3.0 → 10.5.0

package/src/menu/index.ts

@@ -0,0 +1,358 @@
+/**
+ * Interactive TUI Command Center & Tool Navigator for Pyre.
+ */
+import readline from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { readConfig } from '../state/config.js';
+import type { CommandDefinition, MenuState, CommandCategory } from './types.js';
+import { ALL_COMMANDS, CATEGORIES, filterCommands } from './commands.js';
+import { renderMenuScreen } from './render.js';
+
+export interface MenuOptions {
+  theme?: string;
+  initialCategory?: CommandCategory;
+  onExit?: () => void;
+}
+
+export async function runMenu(opts?: MenuOptions): Promise<void> {
+  const config = readConfig();
+  const theme = opts?.theme || config.theme || 'default';
+
+  const state: MenuState = {
+    category: opts?.initialCategory || 'all',
+    categoryIndex: CATEGORIES.findIndex((c) => c.id === (opts?.initialCategory || 'all')) || 0,
+    searchQuery: '',
+    selectedIndex: 0,
+    scrollOffset: 0,
+    inputMode: 'search',
+    argPromptValue: '',
+    activeCommand: null,
+    statusMessage: '',
+    termWidth: process.stdout.columns || 80,
+    termHeight: process.stdout.rows || 24,
+    theme,
+  };
+
+  let isRunning = true;
+  let statusTimer: NodeJS.Timeout | null = null;
+
+  function setStatus(msg: string, durationMs = 3000) {
+    state.statusMessage = msg;
+    if (statusTimer) clearTimeout(statusTimer);
+    statusTimer = setTimeout(() => {
+      state.statusMessage = '';
+      if (isRunning) render();
+    }, durationMs);
+  }
+
+  function getFiltered(): CommandDefinition[] {
+    return filterCommands(ALL_COMMANDS, state.category, state.searchQuery);
+  }
+
+  function render() {
+    if (!isRunning) return;
+    const filtered = getFiltered();
+    const output = renderMenuScreen(state, filtered);
+    process.stdout.write('\x1b[H' + output);
+  }
+
+  function onResize() {
+    state.termWidth = process.stdout.columns || 80;
+    state.termHeight = process.stdout.rows || 24;
+    render();
+  }
+
+  function enterTui() {
+    process.stdout.write('\x1b[?1049h'); // Enter alternate screen buffer
+    process.stdout.write('\x1b[?25l');   // Hide cursor
+    process.stdout.write('\x1b[2J\x1b[H'); // Clear screen
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.isTTY) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.on('resize', onResize);
+    render();
+  }
+
+  function leaveTui() {
+    process.stdout.removeListener('resize', onResize);
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+    process.stdout.write('\x1b[?25h');   // Show cursor
+    process.stdout.write('\x1b[?1049l'); // Leave alternate screen buffer
+  }
+
+  function executeCommand(rawCommandLine: string, isInteractive = false) {
+    leaveTui();
+
+    // Parse tokens from command line string
+    // e.g. "pyre check --detailed" -> ["check", "--detailed"]
+    const tokens = rawCommandLine.trim().split(/\s+/).filter(Boolean);
+    if (tokens[0] === 'pyre') {
+      tokens.shift();
+    }
+
+    console.log(chalk.bold(`\n  🔥 Executing: ${chalk.hex('#ff6a39')(rawCommandLine)}\n`));
+
+    try {
+      // Execute through the current node binary and entry point
+      const scriptPath = process.argv[1];
+      spawnSync(process.argv[0], [scriptPath, ...tokens], {
+        stdio: 'inherit',
+        env: process.env,
+      });
+    } catch (err: any) {
+      console.error(chalk.red(`\n  ✖ Error executing command: ${err.message}`));
+    }
+
+    if (!isInteractive) {
+      console.log(chalk.dim('\n  ─────────────────────────────────────────────────────────────'));
+      console.log(chalk.yellow('  Press any key to return to Command Center (or [q] to exit)...'));
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.once('data', (buf) => {
+          const str = buf.toString().toLowerCase();
+          if (str === 'q' || str === '\u0003') {
+            process.exit(0);
+          }
+          enterTui();
+        });
+        return;
+      }
+    }
+
+    enterTui();
+  }
+
+  enterTui();
+
+  return new Promise<void>((resolve) => {
+    function onKeypress(str: string, key: readline.Key) {
+      if (!isRunning) return;
+      if (!key) return;
+
+      // Ctrl+C exits immediately
+      if (key.ctrl && key.name === 'c') {
+        isRunning = false;
+        leaveTui();
+        if (opts?.onExit) opts.onExit();
+        else process.exit(0);
+        resolve();
+        return;
+      }
+
+      // 1. HELP MODAL MODE
+      if (state.inputMode === 'help') {
+        state.inputMode = 'search';
+        render();
+        return;
+      }
+
+      // 2. PROMPT ARGS MODE
+      if (state.inputMode === 'prompt-args') {
+        if (key.name === 'escape') {
+          state.inputMode = 'search';
+          state.argPromptValue = '';
+          render();
+          return;
+        }
+        if (key.name === 'return' || key.name === 'enter') {
+          const cmd = state.activeCommand;
+          const args = state.argPromptValue.trim();
+          state.inputMode = 'search';
+          state.argPromptValue = '';
+          if (cmd) {
+            const fullCmd = args ? `${cmd.cli} ${args}` : cmd.cli;
+            executeCommand(fullCmd, cmd.interactive);
+          }
+          return;
+        }
+        if (key.name === 'backspace') {
+          state.argPromptValue = state.argPromptValue.slice(0, -1);
+          render();
+          return;
+        }
+        if (str && str.length === 1 && !key.ctrl && !key.meta) {
+          state.argPromptValue += str;
+          render();
+          return;
+        }
+        return;
+      }
+
+      // 3. EDIT COMMAND LINE MODE
+      if (state.inputMode === 'edit-cmd') {
+        if (key.name === 'escape') {
+          state.inputMode = 'search';
+          state.argPromptValue = '';
+          render();
+          return;
+        }
+        if (key.name === 'return' || key.name === 'enter') {
+          const fullCmd = state.argPromptValue.trim();
+          const cmd = state.activeCommand;
+          state.inputMode = 'search';
+          state.argPromptValue = '';
+          if (fullCmd) {
+            executeCommand(fullCmd, cmd?.interactive);
+          }
+          return;
+        }
+        if (key.name === 'backspace') {
+          state.argPromptValue = state.argPromptValue.slice(0, -1);
+          render();
+          return;
+        }
+        if (str && str.length === 1 && !key.ctrl && !key.meta) {
+          state.argPromptValue += str;
+          render();
+          return;
+        }
+        return;
+      }
+
+      // 4. MAIN SEARCH & BROWSING MODE
+      const filtered = getFiltered();
+      const count = filtered.length;
+
+      // Navigation: Up / k
+      if (key.name === 'up' || (key.name === 'k' && state.searchQuery === '')) {
+        if (count > 0) {
+          state.selectedIndex = (state.selectedIndex - 1 + count) % count;
+          render();
+        }
+        return;
+      }
+
+      // Navigation: Down / j
+      if (key.name === 'down' || (key.name === 'j' && state.searchQuery === '')) {
+        if (count > 0) {
+          state.selectedIndex = (state.selectedIndex + 1) % count;
+          render();
+        }
+        return;
+      }
+
+      // Navigation: PageUp
+      if (key.name === 'pageup') {
+        state.selectedIndex = Math.max(0, state.selectedIndex - 6);
+        render();
+        return;
+      }
+
+      // Navigation: PageDown
+      if (key.name === 'pagedown') {
+        state.selectedIndex = Math.min(count - 1, state.selectedIndex + 6);
+        render();
+        return;
+      }
+
+      // Cycle Category: Tab / Shift+Tab
+      if (key.name === 'tab') {
+        const dir = key.shift ? -1 : 1;
+        state.categoryIndex = (state.categoryIndex + dir + CATEGORIES.length) % CATEGORIES.length;
+        state.category = CATEGORIES[state.categoryIndex].id;
+        state.selectedIndex = 0;
+        state.scrollOffset = 0;
+        render();
+        return;
+      }
+
+      // Help: ?
+      if (str === '?' || (str === 'h' && state.searchQuery === '')) {
+        state.inputMode = 'help';
+        render();
+        return;
+      }
+
+      // Copy: c
+      if (str === 'c' && state.searchQuery === '') {
+        const cur = filtered[state.selectedIndex];
+        if (cur) {
+          setStatus(`CLI command: ${cur.cli}`);
+        }
+        return;
+      }
+
+      // Edit Command: e
+      if (str === 'e' && state.searchQuery === '') {
+        const cur = filtered[state.selectedIndex];
+        if (cur) {
+          state.inputMode = 'edit-cmd';
+          state.activeCommand = cur;
+          state.argPromptValue = cur.cli;
+          render();
+        }
+        return;
+      }
+
+      // Execute: Enter / Return
+      if (key.name === 'return' || key.name === 'enter') {
+        const cur = filtered[state.selectedIndex];
+        if (!cur) return;
+
+        if (cur.requiresArgs) {
+          state.inputMode = 'prompt-args';
+          state.activeCommand = cur;
+          state.argPromptValue = cur.requiresArgs.defaultVal || '';
+          render();
+          return;
+        }
+
+        executeCommand(cur.cli, cur.interactive);
+        return;
+      }
+
+      // Backspace in search
+      if (key.name === 'backspace') {
+        if (state.searchQuery.length > 0) {
+          state.searchQuery = state.searchQuery.slice(0, -1);
+          state.selectedIndex = 0;
+          state.scrollOffset = 0;
+          render();
+        }
+        return;
+      }
+
+      // Esc: clear search or exit
+      if (key.name === 'escape') {
+        if (state.searchQuery.length > 0) {
+          state.searchQuery = '';
+          state.selectedIndex = 0;
+          state.scrollOffset = 0;
+          render();
+        } else {
+          isRunning = false;
+          leaveTui();
+          if (opts?.onExit) opts.onExit();
+          else process.exit(0);
+          resolve();
+        }
+        return;
+      }
+
+      // Quit: q (when search is empty)
+      if (str === 'q' && state.searchQuery === '') {
+        isRunning = false;
+        leaveTui();
+        if (opts?.onExit) opts.onExit();
+        else process.exit(0);
+        resolve();
+        return;
+      }
+
+      // Regular character typing into search
+      if (str && str.length === 1 && !key.ctrl && !key.meta) {
+        state.searchQuery += str;
+        state.selectedIndex = 0;
+        state.scrollOffset = 0;
+        render();
+        return;
+      }
+    }
+
+    process.stdin.on('keypress', onKeypress);
+  });
+}

package/src/menu/render.ts

@@ -0,0 +1,272 @@
+/**
+ * TUI Renderer for Pyre's Command Center & Tool Navigator.
+ */
+import chalk from 'chalk';
+import { THEMES, type ThemeName, panel, fitVisible, visLen } from '../formatters/index.js';
+import type { MenuState, CommandDefinition } from './types.js';
+import { CATEGORIES } from './commands.js';
+
+export function renderMenuScreen(state: MenuState, filteredCommands: CommandDefinition[]): string {
+  const width = Math.max(60, state.termWidth || 80);
+  const height = Math.max(16, state.termHeight || 24);
+  const theme = THEMES[state.theme as ThemeName] || THEMES.default;
+  const accent = theme.cpu || chalk.cyan;
+  const border = theme.border || chalk.dim;
+  const highlight = theme.graphs || chalk.hex('#ff6a39');
+
+  const lines: string[] = [];
+
+  // --- 1. Header Banner ---
+  const title = ` 🔥 pyre — Command Center & Tools Navigator `;
+  const headerLeft = accent(chalk.bold(title));
+  const headerRight = chalk.dim(`[?] Help  [q] Quit  `);
+  const topBarInner = headerLeft + '─'.repeat(Math.max(0, width - visLen(title) - visLen(headerRight) - 2)) + headerRight;
+  lines.push(border('╭') + topBarInner + border('╮'));
+
+  const subtitle = ' Browse, search and execute all 38 pyre commands without memorization';
+  lines.push(border('│') + fitVisible(chalk.dim(subtitle), width - 2) + border('│'));
+
+  // --- 2. Search Bar & Status ---
+  let searchInput = state.searchQuery;
+  if (state.inputMode === 'search') {
+    searchInput += chalk.bgWhite.black(' ');
+  }
+  const searchPrompt = ` 🔍 Search: `;
+  const searchContent = searchPrompt + (state.searchQuery ? chalk.bold.yellow(searchInput) : chalk.dim('Type command, keyword or description... (e.g. doctor, clean, smart)'));
+  const matchCount = chalk.dim(`(${filteredCommands.length}/${38} tools) `);
+  const searchBar = fitVisible(searchContent, width - visLen(matchCount) - 2) + matchCount;
+  lines.push(border('├') + border('─'.repeat(width - 2)) + border('┤'));
+  lines.push(border('│') + fitVisible(searchBar, width - 2) + border('│'));
+
+  // --- 3. Category Tabs Bar ---
+  const catTabs = CATEGORIES.map((cat) => {
+    const isSelected = cat.id === state.category;
+    if (isSelected) {
+      return chalk.bgHex('#ff6a39').black(` ${cat.icon} ${cat.name} `);
+    }
+    return chalk.dim(` ${cat.icon} ${cat.name} `);
+  }).join(chalk.dim('│'));
+  lines.push(border('│') + fitVisible(' ' + catTabs, width - 2) + border('│'));
+  lines.push(border('├') + border('─'.repeat(width - 2)) + border('┤'));
+
+  // --- 4. Main Body (Dual Pane or Single Pane) ---
+  const bodyHeight = Math.max(8, height - 9); // Total rows available for list/inspector
+  const isDualPane = width >= 80;
+  const listWidth = isDualPane ? Math.min(46, Math.floor(width * 0.42)) : width - 2;
+  const inspectorWidth = width - 2 - listWidth - (isDualPane ? 1 : 0);
+
+  // Left: Command list rows
+  const listLines: string[] = [];
+  const selectedIdx = Math.min(state.selectedIndex, Math.max(0, filteredCommands.length - 1));
+
+  // Compute scroll window
+  let startIdx = state.scrollOffset;
+  if (selectedIdx < startIdx) {
+    startIdx = selectedIdx;
+  } else if (selectedIdx >= startIdx + bodyHeight) {
+    startIdx = selectedIdx - bodyHeight + 1;
+  }
+  state.scrollOffset = startIdx;
+  const endIdx = Math.min(filteredCommands.length, startIdx + bodyHeight);
+
+  if (filteredCommands.length === 0) {
+    listLines.push(chalk.yellow('  No commands match your search.'));
+    listLines.push(chalk.dim('  Press Esc or backspace to clear query.'));
+  } else {
+    for (let i = startIdx; i < endIdx; i++) {
+      const cmd = filteredCommands[i];
+      const isCur = i === selectedIdx;
+      const badgeText = `[${cmd.badge}]`;
+
+      if (isCur) {
+        const rowText = ` ▶ ${cmd.cli} ${badgeText}`;
+        listLines.push(chalk.bgHex('#ff6a39').black(fitVisible(rowText, listWidth)));
+      } else {
+        const badgeStyled = chalk.dim(badgeText);
+        const cliStyled = chalk.bold(cmd.cli);
+        const rowText = `   ${cliStyled} ${badgeStyled}`;
+        listLines.push(fitVisible(rowText, listWidth));
+      }
+    }
+  }
+
+  while (listLines.length < bodyHeight) {
+    listLines.push(' '.repeat(listWidth));
+  }
+
+  // Right: Inspector Pane
+  const inspectorLines: string[] = [];
+  const curCmd = filteredCommands[selectedIdx];
+
+  if (curCmd && isDualPane) {
+    inspectorLines.push(accent(chalk.bold(` ${curCmd.name} `)) + chalk.dim(`[${curCmd.badge}]`));
+    inspectorLines.push(chalk.dim(` Syntax: `) + highlight(chalk.bold(curCmd.cli)));
+    inspectorLines.push(chalk.dim('─'.repeat(inspectorWidth - 2)));
+    
+    // Description & Help
+    inspectorLines.push(fitVisible(` ${curCmd.description}`, inspectorWidth - 2));
+    inspectorLines.push('');
+    inspectorLines.push(fitVisible(` ${curCmd.detailedHelp}`, inspectorWidth - 2));
+    inspectorLines.push('');
+
+    // Flags section if present
+    if (curCmd.flags && curCmd.flags.length > 0) {
+      inspectorLines.push(chalk.bold.dim(' Options & Flags:'));
+      for (const f of curCmd.flags.slice(0, 4)) {
+        const flagLabel = chalk.yellow(`  ${f.flag}`);
+        const flagDesc = chalk.dim(` - ${f.desc}`);
+        inspectorLines.push(fitVisible(`${flagLabel}${flagDesc}`, inspectorWidth - 2));
+      }
+      inspectorLines.push('');
+    }
+
+    // Example section if present
+    if (curCmd.examples && curCmd.examples.length > 0) {
+      inspectorLines.push(chalk.bold.dim(' Examples:'));
+      for (const ex of curCmd.examples.slice(0, 2)) {
+        inspectorLines.push(chalk.cyan(`  $ ${ex}`));
+      }
+      inspectorLines.push('');
+    }
+
+    // Quick action prompt
+    inspectorLines.push(chalk.dim('─'.repeat(inspectorWidth - 2)));
+    const runPrompt = curCmd.requiresArgs
+      ? chalk.yellow(' [Enter] Enter arguments & Run   [c] Copy   [e] Edit Flags')
+      : chalk.green(' [Enter] Execute Command   [c] Copy   [e] Edit Flags');
+    inspectorLines.push(fitVisible(runPrompt, inspectorWidth - 2));
+  }
+
+  while (inspectorLines.length < bodyHeight) {
+    inspectorLines.push(' '.repeat(inspectorWidth));
+  }
+
+  // Combine Left & Right panes into body rows
+  for (let r = 0; r < bodyHeight; r++) {
+    const left = fitVisible(listLines[r] || '', listWidth);
+    if (isDualPane) {
+      const right = fitVisible(inspectorLines[r] || '', inspectorWidth);
+      lines.push(border('│') + left + border('│') + right + border('│'));
+    } else {
+      lines.push(border('│') + left + border('│'));
+    }
+  }
+
+  // --- 5. Footer Shortcuts ---
+  lines.push(border('├') + border('─'.repeat(width - 2)) + border('┤'));
+  const statusMsg = state.statusMessage ? chalk.yellow(` ${state.statusMessage} `) : '';
+  const shortcuts = ` [↑/↓] Select  [Enter] Run  [Tab] Category  [/] Search  [e] Edit  [?] Help  [q] Quit`;
+  const footerRow = fitVisible(shortcuts, width - visLen(statusMsg) - 2) + statusMsg;
+  lines.push(border('│') + fitVisible(footerRow, width - 2) + border('│'));
+  lines.push(border('╰') + border('─'.repeat(width - 2)) + border('╯'));
+
+  // --- 6. Modal Overlays (if active) ---
+  if (state.inputMode === 'prompt-args' && state.activeCommand) {
+    overlayPromptModal(lines, width, height, state.activeCommand, state.argPromptValue, accent, border);
+  } else if (state.inputMode === 'edit-cmd' && state.activeCommand) {
+    overlayEditCmdModal(lines, width, height, state.activeCommand, state.argPromptValue, accent, border);
+  } else if (state.inputMode === 'help') {
+    overlayHelpModal(lines, width, height, accent, border);
+  }
+
+  return lines.join('\r\n');
+}
+
+/** Render centered modal prompt for command arguments */
+function overlayPromptModal(
+  lines: string[],
+  width: number,
+  height: number,
+  cmd: CommandDefinition,
+  val: string,
+  accent: (s: string) => string,
+  border: (s: string) => string
+) {
+  const modalW = Math.min(width - 4, 64);
+  const promptText = cmd.requiresArgs?.prompt || 'Enter arguments:';
+  const modalLines = [
+    chalk.bold.yellow(`  Run: ${cmd.cli}`),
+    chalk.dim(`  ${cmd.description}`),
+    '',
+    chalk.white(`  ${promptText}`),
+    `  > ${chalk.bold.cyan(val)}${chalk.bgWhite.black(' ')}`,
+    '',
+    chalk.dim('  [Enter] Run Command    [Esc] Cancel'),
+  ];
+
+  const box = panel(` Execute: ${cmd.name} `, modalLines, modalW, accent, border, modalLines.length);
+  stampOverlay(lines, box, width, height);
+}
+
+/** Render centered modal for customizing command line */
+function overlayEditCmdModal(
+  lines: string[],
+  width: number,
+  height: number,
+  cmd: CommandDefinition,
+  val: string,
+  accent: (s: string) => string,
+  border: (s: string) => string
+) {
+  const modalW = Math.min(width - 4, 70);
+  const modalLines = [
+    chalk.bold.yellow(`  Customize Command Line:`),
+    chalk.dim(`  Edit flags or arguments and press Enter to execute.`),
+    '',
+    `  $ ${chalk.bold.cyan(val)}${chalk.bgWhite.black(' ')}`,
+    '',
+    chalk.dim('  [Enter] Execute Custom Command    [Esc] Cancel'),
+  ];
+
+  const box = panel(` Edit & Run `, modalLines, modalW, accent, border, modalLines.length);
+  stampOverlay(lines, box, width, height);
+}
+
+/** Render help overlay */
+function overlayHelpModal(
+  lines: string[],
+  width: number,
+  height: number,
+  accent: (s: string) => string,
+  border: (s: string) => string
+) {
+  const modalW = Math.min(width - 4, 66);
+  const modalLines = [
+    chalk.bold.yellow('  Pyre Command Center — Keyboard Shortcuts'),
+    '',
+    `  ${chalk.cyan('↑ / k, ↓ / j')}       Navigate command list`,
+    `  ${chalk.cyan('PgUp / PgDn')}       Scroll command list fast`,
+    `  ${chalk.cyan('Tab / Shift+Tab')}   Cycle category filters`,
+    `  ${chalk.cyan('1 - 7')}             Jump directly to category`,
+    `  ${chalk.cyan('Enter')}             Execute selected command`,
+    `  ${chalk.cyan('e')}                 Edit flags/arguments before running`,
+    `  ${chalk.cyan('c')}                 Copy command to clipboard / show snippet`,
+    `  ${chalk.cyan('/ (or type)')}       Search / filter commands instantly`,
+    `  ${chalk.cyan('Backspace')}         Delete search query character`,
+    `  ${chalk.cyan('Esc')}               Clear search or close modal`,
+    `  ${chalk.cyan('q')}                 Quit to shell`,
+    '',
+    chalk.dim('  Press any key or Esc to close help...'),
+  ];
+
+  const box = panel(' Help & Shortcuts ', modalLines, modalW, accent, border, modalLines.length);
+  stampOverlay(lines, box, width, height);
+}
+
+/** Stamp a box array in the center of the terminal lines */
+function stampOverlay(screenLines: string[], box: string[], width: number, height: number) {
+  const boxH = box.length;
+  const startRow = Math.max(0, Math.floor((screenLines.length - boxH) / 2));
+  const boxW = visLen(box[0] || '');
+  const startCol = Math.max(0, Math.floor((width - boxW) / 2));
+
+  for (let r = 0; r < boxH; r++) {
+    const targetRow = startRow + r;
+    if (targetRow < screenLines.length) {
+      const orig = screenLines[targetRow];
+      const left = orig.slice(0, startCol);
+      const right = orig.slice(startCol + boxW);
+      screenLines[targetRow] = fitVisible(left, startCol) + box[r] + fitVisible(right, Math.max(0, width - startCol - boxW));
+    }
+  }
+}

package/src/menu/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for Pyre's interactive TUI Command Center.
+ */
+
+export type CommandCategory =
+  | 'all'
+  | 'dashboards'
+  | 'health'
+  | 'performance'
+  | 'maintenance'
+  | 'network'
+  | 'config';
+
+export interface CategoryInfo {
+  id: CommandCategory;
+  name: string;
+  icon: string;
+  badge: string;
+}
+
+export interface CommandFlag {
+  flag: string;
+  desc: string;
+  example?: string;
+}
+
+export interface CommandDefinition {
+  id: string;
+  name: string;
+  cli: string;
+  category: CommandCategory;
+  badge: string;
+  description: string;
+  detailedHelp: string;
+  flags?: CommandFlag[];
+  examples?: string[];
+  tags: string[];
+  /** Whether the command runs interactively (replaces screen) or one-shot */
+  interactive?: boolean;
+  /** Whether the command requires argument input before running */
+  requiresArgs?: {
+    prompt: string;
+    placeholder: string;
+    defaultVal?: string;
+  };
+}
+
+export type MenuInputMode = 'search' | 'prompt-args' | 'edit-cmd' | 'help';
+
+export interface MenuState {
+  category: CommandCategory;
+  categoryIndex: number;
+  searchQuery: string;
+  selectedIndex: number;
+  scrollOffset: number;
+  inputMode: MenuInputMode;
+  argPromptValue: string;
+  activeCommand: CommandDefinition | null;
+  statusMessage: string;
+  termWidth: number;
+  termHeight: number;
+  theme: string;
+}