@moejay/wrightty 0.0.0 → 0.1.1

package/sdks/python/wrightty/terminal.py

@@ -1,333 +0,0 @@
-"""High-level Terminal API for AI agents and automation."""
-
-from __future__ import annotations
-
-import re
-import time
-from typing import Any
-
-from wrightty.client import WrighttyClient, WrighttyError
-
-PORT_RANGE_START = 9420
-PORT_RANGE_END = 9520
-
-
-class Terminal:
-    """High-level terminal automation interface.
-
-    Usage:
-        # Connect to a running wrightty server (daemon or native emulator)
-        term = Terminal.connect()
-        output = term.run("ls -la")
-        print(output)
-
-        # Spawn a new session on a wrightty-server daemon
-        term = Terminal.spawn()
-        term.run("echo hello")
-        term.close()
-    """
-
-    def __init__(self, client: WrighttyClient, session_id: str):
-        self._client = client
-        self._session_id = session_id
-        self._prompt_pattern = r"[$#>%]\s*$"
-
-    @staticmethod
-    def discover(host: str = "127.0.0.1") -> list[dict]:
-        """Scan for running wrightty servers on ports 9420-9520.
-
-        Returns a list of dicts with keys: url, version, implementation, capabilities.
-
-        Example:
-            servers = Terminal.discover()
-            for s in servers:
-                print(f"{s['url']} — {s['implementation']}")
-            # ws://127.0.0.1:9420 — wrightty (headless)
-            # ws://127.0.0.1:9421 — wrightty (wezterm bridge)
-        """
-        found = []
-        for port in range(PORT_RANGE_START, PORT_RANGE_END + 1):
-            url = f"ws://{host}:{port}"
-            try:
-                client = WrighttyClient.connect(url)
-                info = client.request("Wrightty.getInfo")
-                client.close()
-                found.append({
-                    "url": url,
-                    "port": port,
-                    "version": info.get("version", "unknown"),
-                    "implementation": info.get("implementation", "unknown"),
-                    "capabilities": info.get("capabilities", {}),
-                })
-            except (ConnectionError, ConnectionRefusedError, OSError, WrighttyError):
-                continue
-        return found
-
-    @classmethod
-    def connect(
-        cls,
-        url: str | None = None,
-        session_id: str | None = None,
-    ) -> Terminal:
-        """Connect to a wrightty server.
-
-        If no URL is given, auto-discovers the first available server
-        by scanning ports 9420-9440.
-        """
-        if url is None:
-            servers = cls.discover()
-            if not servers:
-                raise ConnectionError(
-                    "No wrightty server found. Start one with:\n"
-                    "  wrightty term --headless\n"
-                    "  wrightty term --bridge-tmux\n"
-                    "  wrightty term --bridge-wezterm"
-                )
-            url = servers[0]["url"]
-
-        client = WrighttyClient.connect(url)
-
-        if session_id is None:
-            result = client.request("Session.list")
-            sessions = result.get("sessions", [])
-            if sessions:
-                session_id = sessions[0]["sessionId"]
-            else:
-                session_id = "0"
-
-        return cls(client, session_id)
-
-    @classmethod
-    def spawn(
-        cls,
-        shell: str | None = None,
-        cols: int = 120,
-        rows: int = 40,
-        cwd: str | None = None,
-        server_url: str = "ws://127.0.0.1:9420",
-    ) -> Terminal:
-        """Connect to a wrightty-server daemon and create a new session."""
-        client = WrighttyClient.connect(server_url)
-
-        params: dict[str, Any] = {"cols": cols, "rows": rows}
-        if shell:
-            params["shell"] = shell
-        if cwd:
-            params["cwd"] = cwd
-
-        result = client.request("Session.create", params)
-        session_id = result["sessionId"]
-
-        term = cls(client, session_id)
-        term.wait_for_prompt(timeout=5)
-        return term
-
-    def close(self):
-        """Close the connection."""
-        self._client.close()
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *args):
-        self.close()
-
-    # --- High-level API ---
-
-    def run(self, command: str, timeout: float = 30) -> str:
-        """Run a command and return its output.
-
-        Sends the command, waits for the prompt to reappear, and returns
-        everything between the command echo and the next prompt.
-        """
-        self.send_text(command + "\n")
-
-        # Wait for prompt to come back.
-        self.wait_for_prompt(timeout=timeout)
-
-        # Read screen and extract output.
-        screen = self.read_screen()
-        lines = screen.strip().split("\n")
-
-        output_lines = []
-        found_cmd = False
-        for line in lines:
-            if not found_cmd:
-                if command in line:
-                    found_cmd = True
-                continue
-            if re.search(self._prompt_pattern, line):
-                break
-            output_lines.append(line)
-
-        return "\n".join(output_lines)
-
-    def send_text(self, text: str):
-        """Send raw text to the terminal."""
-        self._client.request("Input.sendText", {"sessionId": self._session_id, "text": text})
-
-    def send_keys(self, *keys: str):
-        """Send structured keystrokes.
-
-        Examples:
-            term.send_keys("Ctrl+c")
-            term.send_keys("ArrowUp", "Enter")
-            term.send_keys("Escape", ":", "w", "q", "Enter")  # vim :wq
-        """
-        self._client.request(
-            "Input.sendKeys", {"sessionId": self._session_id, "keys": list(keys)}
-        )
-
-    def read_screen(self) -> str:
-        """Read the current visible screen as text."""
-        result = self._client.request("Screen.getText", {"sessionId": self._session_id})
-        return result["text"]
-
-    def screenshot(self, format: str = "svg") -> str | bytes:
-        """Take a screenshot. Returns str for text/svg, bytes for png."""
-        result = self._client.request(
-            "Screen.screenshot", {"sessionId": self._session_id, "format": format}
-        )
-        data = result["data"]
-        if format == "png":
-            import base64
-            return base64.b64decode(data)
-        return data
-
-    def wait_for(self, pattern: str, timeout: float = 30, regex: bool = False) -> str:
-        """Wait until a pattern appears on screen. Returns the screen text when found."""
-        deadline = time.monotonic() + timeout
-        while time.monotonic() < deadline:
-            screen = self.read_screen()
-            if regex:
-                if re.search(pattern, screen):
-                    return screen
-            else:
-                if pattern in screen:
-                    return screen
-            time.sleep(0.2)
-        raise TimeoutError(f"Pattern {pattern!r} not found within {timeout}s")
-
-    def wait_for_prompt(self, timeout: float = 10) -> str:
-        """Wait for the shell prompt to appear."""
-        return self.wait_for(self._prompt_pattern, timeout=timeout, regex=True)
-
-    def set_prompt_pattern(self, pattern: str):
-        """Override the regex used to detect the shell prompt."""
-        self._prompt_pattern = pattern
-
-    def get_size(self) -> tuple[int, int]:
-        """Get terminal dimensions as (cols, rows)."""
-        result = self._client.request("Terminal.getSize", {"sessionId": self._session_id})
-        return result["cols"], result["rows"]
-
-    def resize(self, cols: int, rows: int):
-        """Resize the terminal."""
-        self._client.request(
-            "Terminal.resize", {"sessionId": self._session_id, "cols": cols, "rows": rows}
-        )
-
-    def get_info(self) -> dict:
-        """Get server info and capabilities."""
-        return self._client.request("Wrightty.getInfo")
-
-    # --- Recording ---
-
-    def start_session_recording(self, include_input: bool = False) -> str:
-        """Start recording raw PTY I/O (asciicast v2 format).
-
-        Returns a recording ID. Stop with stop_session_recording().
-        The recording can be played back with `asciinema play`.
-        """
-        result = self._client.request(
-            "Recording.startSession",
-            {"sessionId": self._session_id, "includeInput": include_input},
-        )
-        return result["recordingId"]
-
-    def stop_session_recording(self, recording_id: str) -> dict:
-        """Stop a session recording and return asciicast data.
-
-        Returns dict with keys: format, data, duration, events.
-        Save `data` to a .cast file for asciinema playback.
-        """
-        return self._client.request("Recording.stopSession", {"recordingId": recording_id})
-
-    def start_action_recording(self, format: str = "python") -> str:
-        """Start recording wrightty API calls as a replayable script.
-
-        Args:
-            format: "python", "json", or "cli"
-
-        Returns a recording ID. Stop with stop_action_recording().
-        """
-        result = self._client.request(
-            "Recording.startActions",
-            {"sessionId": self._session_id, "format": format},
-        )
-        return result["recordingId"]
-
-    def stop_action_recording(self, recording_id: str) -> dict:
-        """Stop action recording and return the generated script.
-
-        Returns dict with keys: format, data, actions, duration.
-        """
-        return self._client.request("Recording.stopActions", {"recordingId": recording_id})
-
-    def capture_screen(self, format: str = "svg") -> dict:
-        """Capture a single screen frame.
-
-        Returns dict with keys: frameId, timestamp, format, data.
-        """
-        return self._client.request(
-            "Recording.captureScreen",
-            {"sessionId": self._session_id, "format": format},
-        )
-
-    def start_screen_recording(self, interval_ms: int = 1000, format: str = "svg") -> str:
-        """Start periodic screen capture.
-
-        Args:
-            interval_ms: Capture interval in milliseconds (default: 1000)
-            format: "svg", "text", or "png"
-
-        Returns a recording ID. Stop with stop_screen_recording().
-        """
-        result = self._client.request(
-            "Recording.startScreenCapture",
-            {"sessionId": self._session_id, "intervalMs": interval_ms, "format": format},
-        )
-        return result["recordingId"]
-
-    def stop_screen_recording(self, recording_id: str) -> dict:
-        """Stop screen capture and return all frames.
-
-        Returns dict with keys: frames, duration, frameCount, format.
-        """
-        return self._client.request("Recording.stopScreenCapture", {"recordingId": recording_id})
-
-    def start_video(self, fps: int = 30, format: str = "mp4") -> str:
-        """Start framebuffer video recording (native emulators only).
-
-        Captures the actual rendered pixels via glReadPixels and pipes to ffmpeg.
-        Requires ffmpeg installed on the system.
-
-        Args:
-            fps: Frames per second (default: 30)
-            format: "mp4", "webm", or "gif"
-
-        Returns a recording ID. Stop with stop_video().
-        """
-        result = self._client.request(
-            "Recording.startVideo",
-            {"sessionId": self._session_id, "fps": fps, "format": format},
-        )
-        return result["recordingId"]
-
-    def stop_video(self, recording_id: str) -> dict:
-        """Stop video recording and return metadata.
-
-        Returns dict with keys: format, path, duration, frames, width, height, size.
-        The video file is at the returned `path`.
-        """
-        return self._client.request("Recording.stopVideo", {"recordingId": recording_id})

package/skills/wrightty/SKILL.md

@@ -1,261 +0,0 @@
----
-name: wrightty
-description: Control terminal emulators programmatically via the wrightty protocol. Use when you need to run commands in a real terminal, interact with TUI applications, read terminal screen output, take screenshots, send keystrokes, or automate terminal workflows. Triggers on tasks involving terminal automation, running shell commands through a real PTY, controlling vim/htop/other TUI apps, or capturing terminal output.
-license: MIT
-metadata:
-  author: moejay
-  version: "0.1.0"
----
-
-# wrightty — Terminal Automation Protocol
-
-Wrightty lets you control terminal emulators over WebSocket JSON-RPC. You can run commands, read the screen, send keystrokes, and take screenshots — just like a human would interact with a terminal, but programmatically.
-
-## When to use
-
-- Running shell commands in a real terminal (not subprocess) where you need the full PTY environment
-- Interacting with TUI applications (vim, htop, less, etc.)
-- Reading terminal screen output with colors and formatting
-- Taking terminal screenshots (SVG)
-- Automating interactive terminal workflows
-- Waiting for specific output to appear before proceeding
-
-## Setup
-
-Wrightty needs a terminal backend. Pick one:
-
-**Alacritty (native, zero overhead):**
-```bash
-git clone -b wrightty-support https://github.com/moejay/alacritty.git
-cd alacritty && cargo build --features wrightty
-./target/debug/alacritty --wrightty  # listens on ws://127.0.0.1:9420
-```
-
-**WezTerm (via bridge):**
-```bash
-# Start WezTerm normally, then:
-cargo run -p wrightty-bridge-wezterm  # listens on ws://127.0.0.1:9421
-
-# For flatpak:
-WEZTERM_CMD="flatpak run --command=wezterm org.wezfurlong.wezterm" cargo run -p wrightty-bridge-wezterm
-```
-
-**Headless daemon (no GUI):**
-```bash
-cargo run -p wrightty-server  # listens on ws://127.0.0.1:9420
-```
-
-## Python SDK
-
-The SDK has zero external dependencies.
-
-```python
-from wrightty import Terminal
-
-# Connect to a running terminal
-term = Terminal.connect()                          # ws://127.0.0.1:9420
-term = Terminal.connect("ws://127.0.0.1:9421")    # WezTerm bridge
-
-# Run a command and get output
-output = term.run("cargo test", timeout=120)
-
-# Read the current screen
-screen = term.read_screen()
-
-# Wait for text to appear
-term.wait_for("tests passed", timeout=60)
-term.wait_for(r"error\[\w+\]", regex=True)
-
-# Send keystrokes (TUI apps)
-term.send_keys("Escape", ":", "w", "q", "Enter")  # vim: save and quit
-term.send_keys("Ctrl+c")                           # interrupt
-term.send_keys("ArrowUp", "Enter")                 # repeat last command
-
-# Screenshots
-svg = term.screenshot("svg")
-
-# Terminal info
-cols, rows = term.get_size()
-
-term.close()
-```
-
-Install: `pip install /path/to/wrightty/sdks/python` or set `PYTHONPATH=/path/to/wrightty/sdks/python`.
-
-## CLI
-
-```bash
-wrightty run "ls -la"                              # run command, print output
-wrightty run "cargo test" --timeout 120            # with timeout
-wrightty read                                       # dump current screen
-wrightty send-text "echo hello\n"                   # send raw text
-wrightty send-keys Ctrl+c                           # send keystroke
-wrightty send-keys Escape : w q Enter               # vim: :wq
-wrightty wait-for "BUILD SUCCESS" --timeout 60      # block until text appears
-wrightty screenshot --format svg -o terminal.svg    # take screenshot
-wrightty info                                       # server capabilities
-wrightty size                                       # terminal dimensions
-wrightty --url ws://127.0.0.1:9421 run "ls"         # connect to different server
-```
-
-## MCP Server
-
-Add to your MCP config (Claude, Cursor, etc.):
-
-```json
-{
-  "mcpServers": {
-    "wrightty": {
-      "command": "python3",
-      "args": ["-m", "wrightty.mcp_server"],
-      "env": {
-        "PYTHONPATH": "/path/to/wrightty/sdks/python",
-        "WRIGHTTY_SOCKET": "ws://127.0.0.1:9420"
-      }
-    }
-  }
-}
-```
-
-Available MCP tools:
-
-| Tool | Description |
-|------|-------------|
-| `run_command` | Run a shell command, return output |
-| `read_terminal` | Read current screen text |
-| `send_keys` | Send keystrokes (`["Ctrl+c"]`, `["Escape", ":", "q", "Enter"]`) |
-| `send_text` | Send raw text (use `\n` for newline) |
-| `screenshot` | Terminal screenshot as SVG |
-| `wait_for_text` | Block until pattern appears on screen |
-| `terminal_info` | Terminal dimensions and capabilities |
-
-## Protocol reference
-
-WebSocket JSON-RPC 2.0 on `ws://127.0.0.1:9420`. Full spec: [PROTOCOL.md](https://github.com/moejay/wrightty/blob/main/PROTOCOL.md).
-
-### Core methods
-
-**Run a command:**
-```json
-{"jsonrpc":"2.0","id":1,"method":"Input.sendText","params":{"sessionId":"0","text":"ls -la\n"}}
-```
-
-**Read the screen:**
-```json
-{"jsonrpc":"2.0","id":2,"method":"Screen.getText","params":{"sessionId":"0"}}
-// → {"result":{"text":"$ ls -la\ntotal 140\ndrwxr-xr-x  8 user user 4096 ...\n$"}}
-```
-
-**Send keystrokes:**
-```json
-{"jsonrpc":"2.0","id":3,"method":"Input.sendKeys","params":{"sessionId":"0","keys":["Ctrl+c"]}}
-```
-
-**Take a screenshot:**
-```json
-{"jsonrpc":"2.0","id":4,"method":"Screen.screenshot","params":{"sessionId":"0","format":"svg"}}
-// → {"result":{"format":"svg","data":"<svg ...>"}}
-```
-
-**Get terminal size:**
-```json
-{"jsonrpc":"2.0","id":5,"method":"Terminal.getSize","params":{"sessionId":"0"}}
-// → {"result":{"cols":120,"rows":40}}
-```
-
-**Server capabilities:**
-```json
-{"jsonrpc":"2.0","id":6,"method":"Wrightty.getInfo","params":{}}
-```
-
-### Key names for sendKeys
-
-Single characters: `a`, `1`, `/`, `.`
-Special keys: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `F1`-`F12`
-Modifiers: `Ctrl+c`, `Alt+x`, `Shift+Tab`
-
-### Session management (headless daemon only)
-
-```json
-// Create session
-{"jsonrpc":"2.0","id":1,"method":"Session.create","params":{"cols":80,"rows":24}}
-// → {"result":{"sessionId":"abc-123"}}
-
-// List sessions
-{"jsonrpc":"2.0","id":2,"method":"Session.list","params":{}}
-
-// Destroy session
-{"jsonrpc":"2.0","id":3,"method":"Session.destroy","params":{"sessionId":"abc-123"}}
-```
-
-Native emulator mode uses `"sessionId":"0"` for the active terminal. Session create/destroy is not supported — the emulator manages its own sessions.
-
-## Recording
-
-Three types of recording:
-
-### Session recording (asciicast)
-Records raw PTY I/O with timestamps. Compatible with `asciinema play`.
-
-```python
-rec_id = term.start_session_recording(include_input=True)
-# ... do stuff ...
-result = term.stop_session_recording(rec_id)
-with open("session.cast", "w") as f:
-    f.write(result["data"])
-# Play back: asciinema play session.cast
-```
-
-### Action recording (script generation)
-Records wrightty API calls as a replayable Python/JSON/CLI script. Like Playwright codegen.
-
-```python
-rec_id = term.start_action_recording(format="python")
-# ... do stuff ...
-result = term.stop_action_recording(rec_id)
-print(result["data"])  # prints a Python script that replays the actions
-```
-
-### Screen capture
-Capture individual frames or record periodic screenshots.
-
-```python
-# Single frame
-frame = term.capture_screen(format="svg")
-
-# Periodic capture
-rec_id = term.start_screen_recording(interval_ms=500, format="svg")
-# ... do stuff ...
-result = term.stop_screen_recording(rec_id)
-# result["frames"] is a list of SVG frames with timestamps
-```
-
-### Video recording (native emulators only, requires ffmpeg)
-Captures the actual rendered framebuffer — pixel perfect, including colors, fonts, sixel images, everything on screen.
-
-```python
-rec_id = term.start_video(fps=30, format="mp4")
-# ... do stuff ...
-result = term.stop_video(rec_id)
-print(result["path"])  # /tmp/wrightty-rec_001.mp4
-```
-
-### CLI
-```bash
-wrightty record -o session.cast            # Ctrl+C to stop
-wrightty record-actions -o script.py       # generates Python script
-wrightty record-actions --format cli       # generates shell commands
-```
-
-### MCP tools
-- `start_recording` — starts session + action recording
-- `stop_recording` — stops and returns asciicast data + Python script
-- `capture_screen_frame` — single SVG snapshot
-
-## Tips
-
-- Use `term.run()` for most commands — it sends the command and waits for the prompt to return
-- Use `term.send_keys()` for interactive/TUI apps where you need specific keystrokes
-- Use `term.wait_for()` before reading output from slow commands (builds, tests)
-- The default prompt detection pattern is `[$#>%]\s*$` — override with `term.set_prompt_pattern()` if your prompt is different
-- Screenshots are SVG by default — good for rendering in browsers and docs, and readable by vision models

package/src/lib.rs

@@ -1 +0,0 @@
-// Root package exists only for integration tests.