code-muse 0.0.1__py3-none-any.whl

code_muse/tools/ask_user_question/renderers.py

@@ -0,0 +1,336 @@
+"""Rendering functions for the ask_user_question TUI.
+
+This module contains the panel rendering logic, separated from the main
+TUI logic to keep files under 600 lines.
+"""
+
+import io
+import shutil
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.formatted_text import ANSI
+from rich.console import Console
+from rich.markup import escape as rich_escape
+
+from .constants import (
+    ARROW_DOWN,
+    ARROW_LEFT,
+    ARROW_RIGHT,
+    ARROW_UP,
+    AUTO_ADD_OTHER_OPTION,
+    BORDER_DOUBLE,
+    CHECK_MARK,
+    CURSOR_POINTER,
+    HELP_BORDER_WIDTH,
+    MAX_READABLE_WIDTH,
+    OTHER_OPTION_DESCRIPTION,
+    OTHER_OPTION_LABEL,
+    PANEL_CONTENT_PADDING,
+    PIPE_SEPARATOR,
+    RADIO_FILLED,
+)
+from .theme import get_rich_colors
+
+if TYPE_CHECKING:
+    from .terminal_ui import QuestionUIState
+    from .theme import RichColors
+
+
+def render_question_panel(
+    state: QuestionUIState,
+    colors: RichColors | None = None,
+    available_width: int | None = None,
+) -> ANSI:
+    """Render the right panel with the current question.
+
+    Wraps the inner renderer in a guard so a Rich markup error in user-supplied
+    text can never doom-loop the TUI (the render callback is invoked on every
+    redraw, so an unhandled exception was previously fatal).
+
+    Args:
+        state: The current UI state
+        colors: Optional cached RichColors instance. If None, fetches from config.
+    """
+    try:
+        return _render_question_panel_unsafe(state, colors, available_width)
+    except Exception as exc:  # noqa: BLE001 - intentional: render must never crash
+        # Best-effort fallback. Escape everything; never re-enter Rich markup parsing.
+        buffer = io.StringIO()
+        Console(file=buffer, force_terminal=True, no_color=True).print(
+            f"[render error: {type(exc).__name__}: {exc}]",
+            markup=False,
+        )
+        return ANSI(buffer.getvalue())
+
+
+def _render_question_panel_unsafe(
+    state: QuestionUIState,
+    colors: RichColors | None,
+    available_width: int | None,
+) -> ANSI:
+    """Actual rendering implementation. Caller wraps this in a guard."""
+    if colors is None:
+        colors = get_rich_colors()
+
+    buffer = io.StringIO()
+    # Use available panel width if provided, otherwise fall back to terminal width
+    # Subtract padding to avoid overflow into frame borders
+    if available_width is not None:
+        terminal_width = min(available_width, MAX_READABLE_WIDTH)
+    else:
+        terminal_width = min(shutil.get_terminal_size().columns, MAX_READABLE_WIDTH)
+    console = Console(
+        file=buffer,
+        force_terminal=True,
+        width=terminal_width,
+        legacy_windows=False,
+        color_system="truecolor",
+        no_color=False,
+        force_interactive=True,
+    )
+
+    # Show help overlay if requested
+    if state.show_help:
+        return _render_help_overlay(console, buffer, colors)
+
+    question = state.current_question
+    q_num = state.current_question_index + 1
+    total = len(state.questions)
+    pad = PANEL_CONTENT_PADDING  # Left padding for visual alignment
+
+    # Escape all user-supplied strings before they hit Rich markup. Without this,
+    # a header like '/foo' becomes '[/foo]' which Rich parses as an unmatched
+    # closing tag and raises MarkupError on every redraw (doom-loop).
+    # We escape the whole bracketed-decoration so both '[' and ']' are literal.
+    safe_header_decoration = rich_escape(f"[{question.header}]")
+    safe_question = rich_escape(question.question)
+
+    # Header
+    console.print(
+        f"{pad}[{colors.header}]{safe_header_decoration}[/{colors.header}] "
+        f"[{colors.progress}]({q_num}/{total})[/{colors.progress}]"
+    )
+    console.print()
+
+    # Question text
+    if question.multi_select:
+        console.print(
+            f"{pad}[bold]? {safe_question}[/bold] [dim](select multiple)[/dim]"
+        )
+    else:
+        console.print(f"{pad}[bold]? {safe_question}[/bold]")
+    console.print()
+
+    # Render options
+    for i, option in enumerate(question.options):
+        _render_option(
+            console,
+            label=option.label,
+            description=option.description,
+            is_cursor=state.current_cursor == i,
+            is_selected=state.is_option_selected(i),
+            multi_select=question.multi_select,
+            colors=colors,
+            padding=pad,
+        )
+
+    # Render "Other" option if enabled
+    if AUTO_ADD_OTHER_OPTION:
+        other_idx = len(question.options)
+        # Get the stored "Other" text for this question
+        other_text = state.get_other_text_for_question(state.current_question_index)
+        # Build the description - show stored text if available
+        # Escape user input to prevent Rich markup injection
+        if other_text:
+            other_desc = f'"{rich_escape(other_text)}"'
+        else:
+            other_desc = OTHER_OPTION_DESCRIPTION
+        _render_option(
+            console,
+            label=OTHER_OPTION_LABEL,
+            description=other_desc,
+            is_cursor=state.current_cursor == other_idx,
+            is_selected=state.is_option_selected(other_idx),
+            multi_select=question.multi_select,
+            colors=colors,
+            padding=pad,
+        )
+
+    # If entering "Other" text, show the input field
+    if state.entering_other_text:
+        console.print()
+        console.print(
+            f"{pad}[{colors.input_label}]Enter your custom option:[/{colors.input_label}]"
+        )
+        console.print(
+            f"{pad}[{colors.input_text}]> {state.other_text_buffer}_[/{colors.input_text}]"
+        )
+        console.print()
+        console.print(
+            f"{pad}[{colors.input_hint}]Enter to confirm, Esc to cancel[/{colors.input_hint}]"
+        )
+
+    # Help text at bottom - build dynamically, filtering out None entries
+    console.print()
+    is_last = state.current_question_index == total - 1
+    help_parts = [
+        "Space Toggle" if question.multi_select else "Space Select",
+        "Enter Next" if not is_last else None,
+        f"{ARROW_LEFT}{ARROW_RIGHT} Questions" if total > 1 else None,
+        "Ctrl+S Submit",
+        "? Help",
+    ]
+    separator = f" {PIPE_SEPARATOR} "
+    console.print(
+        f"{pad}[{colors.description}]{separator.join(p for p in help_parts if p)}[/{colors.description}]"
+    )
+
+    # Show timeout warning if approaching timeout
+    if state.should_show_timeout_warning():
+        remaining = state.get_time_remaining()
+        console.print()
+        console.print(
+            f"{pad}[{colors.timeout_warning}]⚠ Timeout in {remaining}s - press any key to continue[/{colors.timeout_warning}]"
+        )
+
+    return ANSI(buffer.getvalue())
+
+
+# Help overlay shortcut data: (section_name, [(primary_key, alt_key_or_None, description), ...])
+_HELP_SECTIONS: list[tuple[str, list[tuple[str, str | None, str]]]] = [
+    (
+        "Navigation:",
+        [
+            (ARROW_UP, "k", "Move up"),
+            (ARROW_DOWN, "j", "Move down"),
+            (ARROW_LEFT, "h", "Previous question"),
+            (ARROW_RIGHT, "l", "Next question"),
+            ("g", None, "Jump to first option"),
+            ("G", None, "Jump to last option"),
+        ],
+    ),
+    (
+        "Selection:",
+        [
+            ("Space", None, "Select option (radio) / Toggle (checkbox)"),
+            ("Enter", None, "Next question (select + advance)"),
+            ("a", None, "Select all (multi-select)"),
+            ("n", None, "Select none (multi-select)"),
+            ("Ctrl+S", None, "Submit all answers"),
+        ],
+    ),
+    (
+        "Other:",
+        [
+            ("Tab", None, "Peek behind (toggle TUI visibility)"),
+            ("?", None, "Toggle this help"),
+            ("Esc", None, "Cancel"),
+            ("Ctrl+C", None, "Cancel"),
+        ],
+    ),
+]
+
+
+def _render_help_overlay(
+    console: Console, buffer: io.StringIO, colors: RichColors
+) -> ANSI:
+    """Render the help overlay using data-driven approach."""
+    pad = PANEL_CONTENT_PADDING
+    border = colors.help_border
+    key_style = colors.help_key
+    section_style = colors.help_section
+
+    border_line = f"{pad}[{border}]{BORDER_DOUBLE * HELP_BORDER_WIDTH}[/{border}]"
+
+    console.print(border_line)
+    console.print(
+        f"{pad}[{colors.help_title}]           KEYBOARD SHORTCUTS[/{colors.help_title}]"
+    )
+    console.print(border_line)
+    console.print()
+
+    for section_name, shortcuts in _HELP_SECTIONS:
+        console.print(f"{pad}[{section_style}]{section_name}[/{section_style}]")
+        for primary, alt, desc in shortcuts:
+            if alt:
+                console.print(
+                    f"{pad}  [{key_style}]{primary}[/{key_style}] / "
+                    f"[{key_style}]{alt}[/{key_style}]       {desc}"
+                )
+            else:
+                console.print(
+                    f"{pad}  [{key_style}]{primary}[/{key_style}]           {desc}"
+                )
+        console.print()
+
+    console.print(border_line)
+    console.print(
+        f"{pad}[{colors.help_close}]Press [{key_style}]?[/{key_style}] to close this help[/{colors.help_close}]"
+    )
+    console.print(border_line)
+
+    return ANSI(buffer.getvalue())
+
+
+def _render_option(
+    console: Console,
+    *,
+    label: str,
+    description: str,
+    is_cursor: bool,
+    is_selected: bool,
+    multi_select: bool,
+    colors: RichColors,
+    padding: str = "",
+) -> None:
+    """Render a single option line.
+
+    Args:
+        console: Rich console to render to
+        label: Option label text
+        description: Option description text
+        is_cursor: Whether cursor is on this option
+        is_selected: Whether this option is selected
+        multi_select: Whether this is a multi-select question
+        colors: RichColors instance (required to avoid repeated config lookups)
+        padding: Left padding string to prepend to each line
+    """
+    # Escape label and description to prevent Rich markup injection
+    label = rich_escape(label)
+    description = rich_escape(description) if description else ""
+
+    cursor_style = colors.cursor
+    selected_style = colors.selected
+    desc_style = colors.description
+
+    # Build the prefix with checkbox or radio button
+    if multi_select:
+        # Checkbox style: [✓] or [ ]
+        checkbox = f"[{CHECK_MARK}]" if is_selected else "[ ]"
+        if is_cursor:
+            prefix = f"[{cursor_style}]{CURSOR_POINTER} {checkbox}[/{cursor_style}]"
+        else:
+            prefix = f"  {checkbox}"
+    else:
+        # Radio button style: (●) or ( )
+        radio = f"({RADIO_FILLED})" if is_selected else "( )"
+        if is_cursor:
+            prefix = f"[{cursor_style}]{CURSOR_POINTER} {radio}[/{cursor_style}]"
+        else:
+            prefix = f"  {radio}"
+
+    # Build the label
+    if is_cursor:
+        label_styled = f"[{cursor_style}]{label}[/{cursor_style}]"
+    elif is_selected:
+        label_styled = f"[{selected_style}]{label}[/{selected_style}]"
+    else:
+        label_styled = label
+
+    # Print option
+    console.print(f"{padding}  {prefix} {label_styled}")
+
+    # Print description if present
+    if description:
+        console.print(f"{padding}      [{desc_style}]{description}[/{desc_style}]")
+    console.print()

code_muse/tools/ask_user_question/terminal_ui.py

@@ -0,0 +1,327 @@
+"""Terminal UI for ask_user_question tool.
+
+Uses prompt_toolkit for a split-panel TUI similar to the /colors command.
+Left panel (20%): Question headers/tabs
+Right panel (80%): Current question with options
+
+Navigation:
+- Left/Right: Switch between questions
+- Up/Down: Navigate options within current question
+- Enter: Select option (single-select) or confirm (multi-select)
+- Space: Toggle option (multi-select only)
+- Esc/Ctrl+C: Cancel
+"""
+
+import time
+
+from .constants import (
+    AUTO_ADD_OTHER_OPTION,
+    DEFAULT_TIMEOUT_SECONDS,
+    LEFT_PANEL_PADDING,
+    MAX_LEFT_PANEL_WIDTH,
+    MIN_LEFT_PANEL_WIDTH,
+    OTHER_OPTION_LABEL,
+    TIMEOUT_WARNING_SECONDS,
+)
+from .models import Question, QuestionAnswer
+
+
+class CancelledException(Exception):
+    """Raised when user cancels the interaction."""
+
+
+class QuestionUIState:
+    """Holds the current UI state for the question interaction."""
+
+    def __init__(self, questions: list[Question]) -> None:
+        """Initialize state with questions.
+
+        Args:
+            questions: List of validated Question objects
+        """
+        self.questions = questions
+        self.current_question_index = 0
+        # For each question, track: cursor position and selected options
+        self.cursor_positions: list[int] = [0] * len(questions)
+        # For multi-select, track selected option indices per question
+        self.selected_options: list[set[int]] = [set() for _ in questions]
+        # For single-select, track the selected option index per question (None = not selected)
+        self.single_selections: list[int | None] = [None] * len(questions)
+        # Store "Other" text per question
+        self.other_texts: list[str | None] = [None] * len(questions)
+        # Track if we're in "Other" text input mode
+        self.entering_other_text = False
+        self.other_text_buffer = ""
+        # Track if help overlay is shown
+        self.show_help = False
+        # Timeout tracking (use monotonic to avoid clock drift/NTP issues)
+        self.timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS
+        self.last_activity_time: float = time.monotonic()
+
+    def reset_activity_timer(self) -> None:
+        """Reset the activity timer (called on user input)."""
+        self.last_activity_time = time.monotonic()
+
+    def get_time_remaining(self) -> int:
+        """Get seconds remaining before timeout."""
+        elapsed = time.monotonic() - self.last_activity_time
+        remaining = self.timeout_seconds - elapsed
+        return max(0, int(remaining))
+
+    def is_timed_out(self) -> bool:
+        """Check if the interaction has timed out."""
+        return self.get_time_remaining() <= 0
+
+    def should_show_timeout_warning(self) -> bool:
+        """Check if we should show the timeout warning."""
+        remaining = self.get_time_remaining()
+        return remaining <= TIMEOUT_WARNING_SECONDS and remaining > 0
+
+    @property
+    def current_question(self) -> Question:
+        """Get the currently displayed question."""
+        return self.questions[self.current_question_index]
+
+    def get_left_panel_width(self) -> int:
+        """Calculate the left panel width based on longest header.
+
+        Returns:
+            Width in characters, including padding for cursor and checkmark.
+        """
+        max_header_len = max(len(q.header) for q in self.questions)
+        width = max_header_len + LEFT_PANEL_PADDING
+        return max(MIN_LEFT_PANEL_WIDTH, min(width, MAX_LEFT_PANEL_WIDTH))
+
+    def get_other_text_for_question(self, index: int) -> str | None:
+        """Get the 'Other' text for a specific question.
+
+        Args:
+            index: Question index
+
+        Returns:
+            The stored other_text or None if not set.
+        """
+        return self.other_texts[index]
+
+    def jump_to_first(self) -> None:
+        """Jump cursor to first option."""
+        self.current_cursor = 0
+
+    def jump_to_last(self) -> None:
+        """Jump cursor to last option."""
+        self.current_cursor = self.total_options - 1
+
+    @property
+    def current_cursor(self) -> int:
+        """Get cursor position for current question."""
+        return self.cursor_positions[self.current_question_index]
+
+    @current_cursor.setter
+    def current_cursor(self, value: int) -> None:
+        """Set cursor position for current question."""
+        self.cursor_positions[self.current_question_index] = value
+
+    @property
+    def total_options(self) -> int:
+        """Get total number of options including 'Other' if enabled."""
+        count = len(self.current_question.options)
+        if AUTO_ADD_OTHER_OPTION:
+            count += 1
+        return count
+
+    def is_question_answered(self, index: int) -> bool:
+        """Check if a question has at least one selection.
+
+        For multi-select: True if any option is selected or Other text provided.
+        For single-select: True if an option is selected.
+        """
+        question = self.questions[index]
+        if question.multi_select:
+            return (
+                len(self.selected_options[index]) > 0
+                or self.other_texts[index] is not None
+            )
+        return self.single_selections[index] is not None
+
+    def is_other_option(self, index: int) -> bool:
+        """Check if the given index is the 'Other' option."""
+        if not AUTO_ADD_OTHER_OPTION:
+            return False
+        return index == len(self.current_question.options)
+
+    def enter_other_text_mode(self) -> None:
+        """Enter text input mode for the 'Other' option.
+
+        This centralizes the logic for starting 'Other' text entry,
+        avoiding duplication in the keyboard handlers.
+        """
+        self.entering_other_text = True
+        self.other_text_buffer = self.other_texts[self.current_question_index] or ""
+
+    def commit_other_text(self) -> None:
+        """Save the other text buffer and mark the Other option as selected.
+
+        This centralizes the logic for confirming an 'Other' text entry,
+        avoiding duplication in the various keyboard handlers.
+        """
+        if not self.other_text_buffer.strip():
+            # Don't save empty/whitespace-only text
+            self.entering_other_text = False
+            self.other_text_buffer = ""
+            return
+
+        self.other_texts[self.current_question_index] = self.other_text_buffer
+        other_idx = len(self.current_question.options)
+        self._select_option_at(self.current_question_index, other_idx)
+        self.entering_other_text = False
+        self.other_text_buffer = ""
+
+    def _select_option_at(self, question_idx: int, option_idx: int) -> None:
+        """Mark an option as selected for the given question.
+
+        Handles both single-select and multi-select modes.
+        """
+        if self.questions[question_idx].multi_select:
+            self.selected_options[question_idx].add(option_idx)
+        else:
+            self.single_selections[question_idx] = option_idx
+
+    def select_all_options(self) -> None:
+        """Select all regular options for the current question (multi-select only)."""
+        if not self.current_question.multi_select:
+            return
+        for i in range(len(self.current_question.options)):
+            self.selected_options[self.current_question_index].add(i)
+
+    def select_no_options(self) -> None:
+        """Clear all selections for the current question (multi-select only)."""
+        if not self.current_question.multi_select:
+            return
+        self.selected_options[self.current_question_index].clear()
+        self.other_texts[self.current_question_index] = None
+
+    def move_cursor_up(self) -> None:
+        """Move cursor up within current question."""
+        if self.current_cursor > 0:
+            self.current_cursor -= 1
+
+    def move_cursor_down(self) -> None:
+        """Move cursor down within current question."""
+        if self.current_cursor < self.total_options - 1:
+            self.current_cursor += 1
+
+    def next_question(self) -> None:
+        """Move to next question."""
+        if self.current_question_index < len(self.questions) - 1:
+            self.current_question_index += 1
+
+    def prev_question(self) -> None:
+        """Move to previous question."""
+        if self.current_question_index > 0:
+            self.current_question_index -= 1
+
+    def toggle_current_option(self) -> None:
+        """Toggle the current option for multi-select questions."""
+        if not self.current_question.multi_select:
+            return
+        cursor = self.current_cursor
+        selected = self.selected_options[self.current_question_index]
+        if cursor in selected:
+            selected.discard(cursor)
+        else:
+            selected.add(cursor)
+
+    def select_current_option(self) -> None:
+        """Select current option for single-select questions."""
+        if self.current_question.multi_select:
+            return
+        self.single_selections[self.current_question_index] = self.current_cursor
+
+    def is_option_selected(self, index: int) -> bool:
+        """Check if an option is selected."""
+        if self.current_question.multi_select:
+            return index in self.selected_options[self.current_question_index]
+        else:
+            return self.single_selections[self.current_question_index] == index
+
+    def _resolve_option_label(
+        self, question: Question, question_idx: int, opt_idx: int
+    ) -> tuple[str, str | None]:
+        """Resolve the label and other_text for an option index.
+
+        Args:
+            question: The question being answered
+            question_idx: Index of the question in self.questions
+            opt_idx: Index of the selected option
+
+        Returns:
+            Tuple of (label, other_text) where other_text is set only for "Other" option
+        """
+        if AUTO_ADD_OTHER_OPTION and opt_idx == len(question.options):
+            return OTHER_OPTION_LABEL, self.other_texts[question_idx]
+        return question.options[opt_idx].label, None
+
+    def build_answers(self) -> list[QuestionAnswer]:
+        """Build the list of answers from current state."""
+        answers = []
+        for i, question in enumerate(self.questions):
+            selected_labels: list[str] = []
+            other_text: str | None = None
+
+            if question.multi_select:
+                # Multi-select: gather all selected option labels
+                for opt_idx in sorted(self.selected_options[i]):
+                    label, opt_other = self._resolve_option_label(question, i, opt_idx)
+                    selected_labels.append(label)
+                    if opt_other is not None:
+                        other_text = opt_other
+            else:
+                # Single-select: get the selected option
+                sel_idx = self.single_selections[i]
+                if sel_idx is not None:
+                    label, other_text = self._resolve_option_label(question, i, sel_idx)
+                    selected_labels.append(label)
+
+            answers.append(
+                QuestionAnswer(
+                    question_header=question.header,
+                    selected_options=selected_labels,
+                    other_text=other_text,
+                )
+            )
+        return answers
+
+
+async def interactive_question_picker(
+    questions: list[Question],
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+) -> tuple[list[QuestionAnswer], bool, bool]:
+    """Show an interactive split-panel TUI for questions.
+
+    Args:
+        questions: List of validated Question objects
+        timeout_seconds: Inactivity timeout in seconds
+
+    Returns:
+        Tuple of (answers, cancelled, timed_out) where:
+        - answers: List of QuestionAnswer objects
+        - cancelled: True if user cancelled
+        - timed_out: True if interaction timed out
+
+    Raises:
+        CancelledException: If user cancels with Esc/Ctrl+C
+    """
+    # Import here to avoid circular dependency with command_runner
+    from code_muse.tools.command_runner import set_awaiting_user_input
+
+    state = QuestionUIState(questions)
+    state.timeout_seconds = timeout_seconds
+    set_awaiting_user_input(True)
+
+    try:
+        from .tui_loop import run_question_tui
+
+        # prompt_toolkit manages alt screen via full_screen=True
+        return await run_question_tui(state)
+    finally:
+        set_awaiting_user_input(False)