overcode 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

overcode/testing/tmux_driver.py

@@ -0,0 +1,223 @@
+"""tmux session management for TUI testing."""
+
+import time
+from typing import Optional
+import libtmux
+
+
+class TUIDriver:
+    """Manages a tmux session for testing TUI applications.
+
+    This class provides a simple interface to:
+    - Start a TUI app in a tmux session with controlled dimensions
+    - Send keystrokes to the app
+    - Capture the screen content (with ANSI codes)
+    - Wait for specific content to appear
+    - Clean up the session
+    """
+
+    def __init__(
+        self,
+        session_name: str = "tui-eye",
+        socket_name: Optional[str] = None,
+    ):
+        """Initialize the TUI driver.
+
+        Args:
+            session_name: Name for the tmux session
+            socket_name: Optional tmux socket name (for isolation)
+        """
+        self.session_name = session_name
+        self.socket_name = socket_name
+        self.server: Optional[libtmux.Server] = None
+        self.session: Optional[libtmux.Session] = None
+
+    def start(
+        self,
+        command: str,
+        width: int = 120,
+        height: int = 40,
+        env: Optional[dict[str, str]] = None,
+    ) -> None:
+        """Start a TUI application in a new tmux session.
+
+        Args:
+            command: The command to run (e.g., "overcode supervisor")
+            width: Terminal width in characters
+            height: Terminal height in characters
+            env: Optional environment variables to set
+        """
+        # Kill any existing session with this name
+        self.stop()
+
+        # Create server connection
+        if self.socket_name:
+            self.server = libtmux.Server(socket_name=self.socket_name)
+        else:
+            self.server = libtmux.Server()
+
+        # Create new session
+        self.session = self.server.new_session(
+            session_name=self.session_name,
+            window_command=command,
+            x=width,
+            y=height,
+            environment=env,
+        )
+
+    def send_keys(self, *keys: str, enter: bool = False) -> None:
+        """Send keystrokes to the TUI.
+
+        Args:
+            keys: Key names to send (e.g., "j", "k", "Enter", "escape")
+            enter: Whether to send Enter after all keys
+        """
+        if not self.session:
+            self.connect()
+        if not self.session:
+            raise RuntimeError("No active session. Call start() first.")
+
+        pane = self.session.active_window.active_pane
+
+        for key in keys:
+            # Map common key names
+            key_map = {
+                "enter": "Enter",
+                "escape": "Escape",
+                "esc": "Escape",
+                "tab": "Tab",
+                "space": "Space",
+                "up": "Up",
+                "down": "Down",
+                "left": "Left",
+                "right": "Right",
+                "backspace": "BSpace",
+            }
+            mapped_key = key_map.get(key.lower(), key)
+            pane.send_keys(mapped_key, enter=False)
+
+        if enter:
+            pane.send_keys("Enter", enter=False)
+
+    def capture(self, with_ansi: bool = True) -> str:
+        """Capture the current screen content.
+
+        Args:
+            with_ansi: Whether to include ANSI escape codes
+
+        Returns:
+            The screen content as a string
+        """
+        if not self.session:
+            self.connect()
+        if not self.session:
+            raise RuntimeError("No active session. Call start() first.")
+
+        pane = self.session.active_window.active_pane
+
+        # Use capture_pane with escape sequences if requested
+        if with_ansi:
+            # -e preserves ANSI escape sequences
+            # -p prints to stdout
+            content = pane.cmd("capture-pane", "-e", "-p").stdout
+        else:
+            content = pane.cmd("capture-pane", "-p").stdout
+
+        return "\n".join(content) if isinstance(content, list) else content
+
+    def wait_for(
+        self,
+        text: str,
+        timeout: float = 10.0,
+        poll_interval: float = 0.2,
+    ) -> bool:
+        """Wait for specific text to appear on screen.
+
+        Args:
+            text: The text to wait for
+            timeout: Maximum time to wait in seconds
+            poll_interval: Time between checks in seconds
+
+        Returns:
+            True if text was found, False if timeout occurred
+        """
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            content = self.capture(with_ansi=False)
+            if text in content:
+                return True
+            time.sleep(poll_interval)
+
+        return False
+
+    def stop(self) -> None:
+        """Stop and clean up the tmux session."""
+        if self.session:
+            try:
+                self.session.kill()
+            except Exception:
+                pass
+            self.session = None
+
+        # Always try to kill by name, connecting first if needed
+        try:
+            if not self.server:
+                if self.socket_name:
+                    self.server = libtmux.Server(socket_name=self.socket_name)
+                else:
+                    self.server = libtmux.Server()
+
+            for session in self.server.sessions:
+                if session.name == self.session_name:
+                    session.kill()
+                    break
+        except Exception:
+            pass
+
+    def __enter__(self) -> "TUIDriver":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit - ensures cleanup."""
+        self.stop()
+
+    def connect(self) -> bool:
+        """Connect to an existing tmux session.
+
+        Returns:
+            True if successfully connected, False if session doesn't exist
+        """
+        if self.socket_name:
+            self.server = libtmux.Server(socket_name=self.socket_name)
+        else:
+            self.server = libtmux.Server()
+
+        try:
+            for session in self.server.sessions:
+                if session.name == self.session_name:
+                    self.session = session
+                    return True
+        except Exception:
+            pass
+
+        return False
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the session is still running."""
+        # First try to connect if we don't have a session reference
+        if not self.session:
+            self.connect()
+
+        if not self.session:
+            return False
+
+        try:
+            # Try to access the session to verify it exists
+            _ = self.session.name
+            return True
+        except Exception:
+            self.session = None
+            return False

overcode/testing/tui_eye.py

@@ -0,0 +1,185 @@
+"""tui-eye: Visual TUI testing tool for Claude Code.
+
+This CLI tool allows Claude Code to "see" TUI applications by:
+1. Running them in a controlled tmux session
+2. Capturing screenshots as PNG images
+3. Sending keystrokes for interaction
+
+Example usage:
+    tui-eye start "overcode supervisor" --size 120x40
+    tui-eye screenshot /tmp/tui.png
+    tui-eye send j j enter
+    tui-eye wait-for "Session:"
+    tui-eye stop
+"""
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+import typer
+
+from .tmux_driver import TUIDriver
+from .renderer import render_terminal_to_png
+
+app = typer.Typer(
+    name="tui-eye",
+    help="Visual TUI testing tool - gives Claude Code 'eyes' into TUI apps",
+)
+
+# Global driver instance (persists between commands via state file)
+STATE_FILE = Path("/tmp/tui-eye-state")
+DEFAULT_SESSION = "tui-eye"
+
+
+def _get_driver() -> TUIDriver:
+    """Get or create a TUI driver instance."""
+    session_name = DEFAULT_SESSION
+    if STATE_FILE.exists():
+        session_name = STATE_FILE.read_text().strip() or DEFAULT_SESSION
+    return TUIDriver(session_name=session_name)
+
+
+def _save_state(session_name: str) -> None:
+    """Save the current session name to state file."""
+    STATE_FILE.write_text(session_name)
+
+
+def _clear_state() -> None:
+    """Clear the state file."""
+    if STATE_FILE.exists():
+        STATE_FILE.unlink()
+
+
+@app.command()
+def start(
+    command: Annotated[str, typer.Argument(help="Command to run in the TUI")],
+    size: Annotated[str, typer.Option(help="Terminal size as WIDTHxHEIGHT")] = "220x40",
+    session: Annotated[str, typer.Option(help="tmux session name")] = DEFAULT_SESSION,
+) -> None:
+    """Start a TUI application in a tmux session."""
+    # Parse size
+    try:
+        width, height = map(int, size.lower().split("x"))
+    except ValueError:
+        typer.echo(f"Error: Invalid size format '{size}'. Use WIDTHxHEIGHT (e.g., 120x40)")
+        raise typer.Exit(1)
+
+    driver = TUIDriver(session_name=session)
+
+    typer.echo(f"Starting TUI: {command}")
+    typer.echo(f"Size: {width}x{height}")
+    typer.echo(f"Session: {session}")
+
+    driver.start(command, width=width, height=height)
+    _save_state(session)
+
+    typer.echo("TUI started. Use 'tui-eye screenshot' to capture.")
+
+
+@app.command()
+def stop() -> None:
+    """Stop the TUI session and clean up."""
+    driver = _get_driver()
+    driver.stop()
+    _clear_state()
+    typer.echo("TUI session stopped.")
+
+
+@app.command()
+def screenshot(
+    output: Annotated[
+        str, typer.Argument(help="Output PNG file path")
+    ] = "/tmp/tui-screenshot.png",
+    width: Annotated[int, typer.Option(help="Terminal width for rendering")] = 220,
+    height: Annotated[int, typer.Option(help="Terminal height for rendering")] = 45,
+) -> None:
+    """Capture a screenshot of the TUI as a PNG image."""
+    driver = _get_driver()
+
+    if not driver.is_running:
+        typer.echo("Error: No TUI session running. Use 'tui-eye start' first.")
+        raise typer.Exit(1)
+
+    # Capture with ANSI codes
+    content = driver.capture(with_ansi=True)
+
+    # Render to PNG
+    output_path = render_terminal_to_png(
+        content,
+        output,
+        width=width,
+        height=height,
+    )
+
+    typer.echo(f"Screenshot saved: {output_path}")
+
+
+@app.command()
+def capture(
+    text: Annotated[bool, typer.Option("--text", help="Output plain text (no ANSI)")] = False,
+) -> None:
+    """Capture and print the current screen content."""
+    driver = _get_driver()
+
+    if not driver.is_running:
+        typer.echo("Error: No TUI session running. Use 'tui-eye start' first.")
+        raise typer.Exit(1)
+
+    content = driver.capture(with_ansi=not text)
+    typer.echo(content)
+
+
+@app.command()
+def send(
+    keys: Annotated[list[str], typer.Argument(help="Keys to send (e.g., j k enter)")],
+) -> None:
+    """Send keystrokes to the TUI."""
+    driver = _get_driver()
+
+    if not driver.is_running:
+        typer.echo("Error: No TUI session running. Use 'tui-eye start' first.")
+        raise typer.Exit(1)
+
+    driver.send_keys(*keys)
+    typer.echo(f"Sent keys: {' '.join(keys)}")
+
+
+@app.command("wait-for")
+def wait_for(
+    text: Annotated[str, typer.Argument(help="Text to wait for")],
+    timeout: Annotated[float, typer.Option(help="Timeout in seconds")] = 10.0,
+) -> None:
+    """Wait for specific text to appear on screen."""
+    driver = _get_driver()
+
+    if not driver.is_running:
+        typer.echo("Error: No TUI session running. Use 'tui-eye start' first.")
+        raise typer.Exit(1)
+
+    typer.echo(f"Waiting for: '{text}' (timeout: {timeout}s)")
+
+    if driver.wait_for(text, timeout=timeout):
+        typer.echo("Found!")
+    else:
+        typer.echo(f"Timeout: text '{text}' not found after {timeout}s")
+        raise typer.Exit(1)
+
+
+@app.command()
+def status() -> None:
+    """Check the status of the TUI session."""
+    driver = _get_driver()
+
+    if driver.is_running:
+        typer.echo(f"Session '{driver.session_name}' is running.")
+    else:
+        typer.echo("No TUI session running.")
+
+
+def main() -> None:
+    """Main entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

overcode/testing/tui_eye_skill.md

@@ -0,0 +1,187 @@
+# TUI Eye - Visual TUI Testing Skill
+
+```yaml
+---
+name: tui-eye
+description: Interactive visual testing of TUI applications. Use when testing the overcode supervisor TUI, validating layouts, or running smoke tests.
+disable-model-invocation: true
+---
+```
+
+You are performing visual TUI testing using the `tui-eye` tool. This tool gives you "eyes" into TUI applications by capturing screenshots as PNG images that you can read and analyze.
+
+## Core Commands
+
+```bash
+# Start a TUI in a controlled tmux session (220x40 default)
+tui-eye start "overcode monitor" --size 220x40
+
+# Capture screenshot for visual inspection
+tui-eye screenshot /tmp/tui.png
+
+# Read the screenshot (use Claude Code's Read tool)
+# Then analyze: layout, alignment, colors, text overflow, etc.
+
+# Send keystrokes
+tui-eye send j j enter      # Navigate down twice, press enter
+tui-eye send h              # Toggle help overlay
+tui-eye send escape         # Close dialogs/cancel
+
+# Wait for content to appear
+tui-eye wait-for "Session:" --timeout 10
+
+# Get text-only capture (for searching/assertions)
+tui-eye capture --text
+
+# Check session status
+tui-eye status
+
+# Clean up when done
+tui-eye stop
+```
+
+## Workflow: Visual Testing
+
+1. **Start the TUI**
+   ```bash
+   tui-eye start "overcode monitor" --size 220x40
+   ```
+
+2. **Capture & Analyze**
+   ```bash
+   tui-eye screenshot /tmp/check.png
+   ```
+   Then read `/tmp/check.png` and visually inspect:
+   - Is the layout correct?
+   - Are columns aligned?
+   - Is text truncated or wrapped unexpectedly?
+   - Are colors/status indicators showing correctly?
+
+3. **Interact**
+   ```bash
+   tui-eye send j       # Navigate
+   tui-eye send enter   # Select/confirm
+   tui-eye send h       # Toggle help
+   ```
+
+4. **Verify Changes**
+   ```bash
+   tui-eye screenshot /tmp/after.png
+   ```
+   Compare to expected state.
+
+5. **Clean Up**
+   ```bash
+   tui-eye stop
+   ```
+
+## Key Mappings
+
+| Key | tmux Name | Description |
+|-----|-----------|-------------|
+| `j` | j | Navigate down |
+| `k` | k | Navigate up |
+| `enter` | Enter | Confirm/select |
+| `escape` | Escape | Cancel/close |
+| `h` | h | Toggle help |
+| `q` | q | Quit (some TUIs) |
+| `tab` | Tab | Next field |
+| `space` | Space | Toggle/expand |
+
+## Example: Smoke Test
+
+```bash
+# Start supervisor TUI
+tui-eye start "overcode monitor" --size 220x45
+
+# Wait for initial render
+tui-eye wait-for "Timeline:" --timeout 10
+
+# Capture initial state
+tui-eye screenshot /tmp/smoke-1.png
+# [Read /tmp/smoke-1.png - verify layout looks correct]
+
+# Test help overlay
+tui-eye send h
+tui-eye screenshot /tmp/smoke-help.png
+# [Read - verify help is displayed]
+
+tui-eye send h
+tui-eye screenshot /tmp/smoke-help-closed.png
+# [Read - verify help closed, main view restored]
+
+# Navigate if there are sessions
+tui-eye send j j
+tui-eye screenshot /tmp/smoke-nav.png
+# [Read - verify navigation worked]
+
+# Done
+tui-eye stop
+```
+
+## Example: Multi-Agent Monitoring
+
+```bash
+# Launch some test agents first
+overcode launch --name test-agent-1 --prompt "Write hello world"
+overcode launch --name test-agent-2 --prompt "List files"
+
+# Start monitor
+tui-eye start "overcode monitor" --size 220x45
+
+# Periodic monitoring loop
+tui-eye wait-for "test-agent" --timeout 30
+tui-eye screenshot /tmp/monitor-1.png
+# [Read - check agent statuses, timelines]
+
+# If an agent needs attention, navigate and interact
+tui-eye send j enter   # Select agent
+tui-eye screenshot /tmp/agent-detail.png
+# [Read - see agent output]
+
+# Continue monitoring...
+tui-eye stop
+```
+
+## Visual Checks to Perform
+
+When reading screenshots, check for:
+
+- **Layout**: Header, timeline, agent list all visible?
+- **Alignment**: Columns aligned, percentages right-justified?
+- **Colors**: Status indicators using correct colors (green=running, red=waiting)?
+- **Text**: No unexpected wrapping or truncation?
+- **Timeline**: Bars extending full width? Percentage shown?
+- **Responsiveness**: After interactions, UI updated correctly?
+
+## Troubleshooting
+
+**Screenshot too narrow / lines wrapping:**
+```bash
+tui-eye screenshot /tmp/x.png --width 220 --height 45
+```
+
+**Can't see full content:**
+Increase height:
+```bash
+tui-eye start "overcode monitor" --size 220x60
+```
+
+**Session already exists:**
+```bash
+tui-eye stop
+tui-eye start "overcode monitor"
+```
+
+**Keys not working:**
+Check session is running:
+```bash
+tui-eye status
+```
+
+## Arguments
+
+`$ARGUMENTS` - Optional test scenario to run. Examples:
+- `help-toggle` - Test the help overlay toggle
+- `navigation` - Test up/down navigation
+- `full-smoke` - Run complete smoke test

overcode/tmux_manager.py

@@ -133,9 +133,23 @@ class TmuxManager:
 
             # Send text first (if any)
             if keys:
-                pane.send_keys(keys, enter=False)
-                # Small delay for Claude Code to process text
-                time.sleep(0.1)
+                # Special handling for ! commands (#139)
+                # Claude Code requires ! to be sent separately to trigger mode switch
+                # to bash mode before receiving the rest of the command
+                if keys.startswith('!') and len(keys) > 1:
+                    # Send ! first
+                    pane.send_keys('!', enter=False)
+                    # Wait for mode switch to process
+                    time.sleep(0.15)
+                    # Send the rest (without the !)
+                    rest = keys[1:]
+                    if rest:
+                        pane.send_keys(rest, enter=False)
+                        time.sleep(0.1)
+                else:
+                    pane.send_keys(keys, enter=False)
+                    # Small delay for Claude Code to process text
+                    time.sleep(0.1)
 
             # Send Enter separately
             if enter: