wrightty 0.1.0__tar.gz

wrightty-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: wrightty
+Version: 0.1.0
+Summary: Python SDK for the Wrightty terminal automation protocol
+Author: Moe Jay
+License: MIT
+Project-URL: Homepage, https://github.com/moejay/wrightty
+Project-URL: Repository, https://github.com/moejay/wrightty
+Project-URL: Issues, https://github.com/moejay/wrightty/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Software Development :: Testing
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == "cli"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+
+# wrightty (Python SDK)
+
+Python SDK for the [Wrightty](https://github.com/moejay/wrightty) terminal automation protocol.
+
+Control any terminal emulator programmatically — send keystrokes, read the screen, take screenshots, and run commands over WebSocket JSON-RPC.
+
+## Install
+
+```bash
+pip install wrightty
+# with MCP server:
+pip install wrightty[mcp]
+```
+
+You also need a wrightty server running. Install it via:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/moejay/wrightty/main/install.sh | sh
+# or
+cargo install wrightty
+```
+
+## Quick start
+
+```python
+from wrightty import Terminal
+
+# Connect to a running wrightty server (auto-discovers)
+term = Terminal.connect()
+
+# Run a command and get its output
+output = term.run("cargo test")
+print(output)
+
+# Read the screen
+screen = term.read_screen()
+
+# Send keystrokes
+term.send_keys("Ctrl+c")
+term.send_keys("Escape", ":", "w", "q", "Enter")
+
+# Wait for text to appear
+term.wait_for("BUILD SUCCESS", timeout=60)
+
+# Screenshots
+svg = term.screenshot("svg")
+
+# Recording
+rec_id = term.start_session_recording()
+term.run("make build")
+result = term.stop_session_recording(rec_id)
+open("build.cast", "w").write(result["data"])  # asciinema play
+
+term.close()
+```
+
+## Starting a server
+
+First start a wrightty terminal server:
+
+```bash
+wrightty term --headless                 # virtual PTY, no GUI
+wrightty term --bridge-tmux              # attach to tmux
+wrightty term --bridge-wezterm           # attach to WezTerm
+wrightty term --bridge-kitty             # attach to Kitty
+wrightty term --bridge-zellij            # attach to Zellij
+wrightty term --bridge-ghostty           # attach to Ghostty
+```
+
+Then connect from Python as shown above.
+
+## MCP server (for Claude, Cursor, etc.)
+
+```bash
+pip install wrightty[mcp]
+```
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "wrightty": {
+      "command": "python3",
+      "args": ["-m", "wrightty.mcp_server"],
+      "env": { "WRIGHTTY_SOCKET": "ws://127.0.0.1:9420" }
+    }
+  }
+}
+```
+
+See the [main repository](https://github.com/moejay/wrightty) for full docs.
+
+## License
+
+MIT

wrightty-0.1.0/README.md

@@ -0,0 +1,96 @@
+# wrightty (Python SDK)
+
+Python SDK for the [Wrightty](https://github.com/moejay/wrightty) terminal automation protocol.
+
+Control any terminal emulator programmatically — send keystrokes, read the screen, take screenshots, and run commands over WebSocket JSON-RPC.
+
+## Install
+
+```bash
+pip install wrightty
+# with MCP server:
+pip install wrightty[mcp]
+```
+
+You also need a wrightty server running. Install it via:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/moejay/wrightty/main/install.sh | sh
+# or
+cargo install wrightty
+```
+
+## Quick start
+
+```python
+from wrightty import Terminal
+
+# Connect to a running wrightty server (auto-discovers)
+term = Terminal.connect()
+
+# Run a command and get its output
+output = term.run("cargo test")
+print(output)
+
+# Read the screen
+screen = term.read_screen()
+
+# Send keystrokes
+term.send_keys("Ctrl+c")
+term.send_keys("Escape", ":", "w", "q", "Enter")
+
+# Wait for text to appear
+term.wait_for("BUILD SUCCESS", timeout=60)
+
+# Screenshots
+svg = term.screenshot("svg")
+
+# Recording
+rec_id = term.start_session_recording()
+term.run("make build")
+result = term.stop_session_recording(rec_id)
+open("build.cast", "w").write(result["data"])  # asciinema play
+
+term.close()
+```
+
+## Starting a server
+
+First start a wrightty terminal server:
+
+```bash
+wrightty term --headless                 # virtual PTY, no GUI
+wrightty term --bridge-tmux              # attach to tmux
+wrightty term --bridge-wezterm           # attach to WezTerm
+wrightty term --bridge-kitty             # attach to Kitty
+wrightty term --bridge-zellij            # attach to Zellij
+wrightty term --bridge-ghostty           # attach to Ghostty
+```
+
+Then connect from Python as shown above.
+
+## MCP server (for Claude, Cursor, etc.)
+
+```bash
+pip install wrightty[mcp]
+```
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "wrightty": {
+      "command": "python3",
+      "args": ["-m", "wrightty.mcp_server"],
+      "env": { "WRIGHTTY_SOCKET": "ws://127.0.0.1:9420" }
+    }
+  }
+}
+```
+
+See the [main repository](https://github.com/moejay/wrightty) for full docs.
+
+## License
+
+MIT

wrightty-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wrightty"
+version = "0.1.0"
+description = "Python SDK for the Wrightty terminal automation protocol"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Moe Jay"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Terminals",
+    "Topic :: Software Development :: Testing",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+cli = ["click>=8.0"]
+mcp = ["mcp>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/moejay/wrightty"
+Repository = "https://github.com/moejay/wrightty"
+Issues = "https://github.com/moejay/wrightty/issues"
+
+[project.scripts]
+wrightty-py = "wrightty.cli:main"
+
+[project.entry-points."mcp.servers"]
+wrightty = "wrightty.mcp_server:serve"

wrightty-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wrightty-0.1.0/wrightty/__init__.py

@@ -0,0 +1,6 @@
+from wrightty.terminal import Terminal
+
+discover = Terminal.discover
+
+__all__ = ["Terminal", "discover"]
+__version__ = "0.1.0"

wrightty-0.1.0/wrightty/cli.py

@@ -0,0 +1,210 @@
+"""Wrightty CLI — control terminals from the command line."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from wrightty.terminal import Terminal
+
+
+@click.group()
+@click.option("--url", default=None, help="Wrightty server URL (default: auto-discover)")
+@click.option("--session", default=None, help="Session ID (default: auto-detect)")
+@click.pass_context
+def main(ctx, url, session):
+    """Wrightty — Playwright for terminals."""
+    ctx.ensure_object(dict)
+    ctx.obj["url"] = url
+    ctx.obj["session"] = session
+
+
+def _connect(ctx) -> Terminal:
+    return Terminal.connect(ctx.obj["url"], ctx.obj["session"])
+
+
+@main.command()
+@click.argument("command")
+@click.option("--timeout", default=30, type=float, help="Timeout in seconds")
+@click.pass_context
+def run(ctx, command, timeout):
+    """Run a command and print its output."""
+    term = _connect(ctx)
+    try:
+        output = term.run(command, timeout=timeout)
+        click.echo(output)
+    finally:
+        term.close()
+
+
+@main.command("read")
+@click.pass_context
+def read_screen(ctx):
+    """Read the current terminal screen."""
+    term = _connect(ctx)
+    try:
+        click.echo(term.read_screen())
+    finally:
+        term.close()
+
+
+@main.command("send-text")
+@click.argument("text")
+@click.pass_context
+def send_text(ctx, text):
+    """Send raw text to the terminal."""
+    term = _connect(ctx)
+    try:
+        # Interpret \\n as actual newlines.
+        text = text.replace("\\n", "\n")
+        term.send_text(text)
+    finally:
+        term.close()
+
+
+@main.command("send-keys")
+@click.argument("keys", nargs=-1, required=True)
+@click.pass_context
+def send_keys(ctx, keys):
+    """Send keystrokes to the terminal.
+
+    Examples:
+        wrightty send-keys Ctrl+c
+        wrightty send-keys Escape : w q Enter
+    """
+    term = _connect(ctx)
+    try:
+        term.send_keys(*keys)
+    finally:
+        term.close()
+
+
+@main.command("wait-for")
+@click.argument("pattern")
+@click.option("--timeout", default=30, type=float, help="Timeout in seconds")
+@click.option("--regex", is_flag=True, help="Treat pattern as regex")
+@click.pass_context
+def wait_for(ctx, pattern, timeout, regex):
+    """Wait until text appears on screen."""
+    term = _connect(ctx)
+    try:
+        screen = term.wait_for(pattern, timeout=timeout, regex=regex)
+        click.echo(screen)
+    except TimeoutError as e:
+        click.echo(str(e), err=True)
+        sys.exit(1)
+    finally:
+        term.close()
+
+
+@main.command()
+@click.option("--format", "fmt", default="svg", type=click.Choice(["text", "svg", "png"]))
+@click.option("--output", "-o", default=None, help="Output file (default: stdout)")
+@click.pass_context
+def screenshot(ctx, fmt, output):
+    """Take a terminal screenshot."""
+    term = _connect(ctx)
+    try:
+        data = term.screenshot(fmt)
+        if output:
+            mode = "wb" if fmt == "png" else "w"
+            with open(output, mode) as f:
+                f.write(data)
+            click.echo(f"Screenshot saved to {output}")
+        else:
+            if fmt == "png":
+                sys.stdout.buffer.write(data)
+            else:
+                click.echo(data)
+    finally:
+        term.close()
+
+
+@main.command()
+@click.pass_context
+def info(ctx):
+    """Show server info and capabilities."""
+    term = _connect(ctx)
+    try:
+        info = term.get_info()
+        click.echo(json.dumps(info, indent=2))
+    finally:
+        term.close()
+
+
+@main.command()
+@click.pass_context
+def size(ctx):
+    """Get terminal dimensions."""
+    term = _connect(ctx)
+    try:
+        cols, rows = term.get_size()
+        click.echo(f"{cols}x{rows}")
+    finally:
+        term.close()
+
+
+@main.command()
+def discover():
+    """Discover running wrightty servers on ports 9420-9520."""
+    servers = Terminal.discover()
+    if not servers:
+        click.echo("No wrightty servers found.")
+        return
+    for s in servers:
+        click.echo(f"  {s['url']}  {s['implementation']} v{s['version']}")
+
+
+@main.command()
+@click.option("--output", "-o", default=None, help="Output file (default: recording.cast)")
+@click.option("--include-input", is_flag=True, help="Also record input keystrokes")
+@click.pass_context
+def record(ctx, output, include_input):
+    """Record a terminal session (asciicast format). Press Ctrl+C to stop."""
+    output = output or "recording.cast"
+    term = _connect(ctx)
+    try:
+        rec_id = term.start_session_recording(include_input=include_input)
+        click.echo(f"Recording... (press Ctrl+C to stop, saving to {output})")
+        try:
+            import signal
+            signal.pause()
+        except KeyboardInterrupt:
+            pass
+        result = term.stop_session_recording(rec_id)
+        with open(output, "w") as f:
+            f.write(result["data"])
+        click.echo(f"Saved {result['events']} events, {result['duration']:.1f}s to {output}")
+    finally:
+        term.close()
+
+
+@main.command("record-actions")
+@click.option("--output", "-o", default=None, help="Output file")
+@click.option("--format", "fmt", default="python", type=click.Choice(["python", "json", "cli"]))
+@click.pass_context
+def record_actions(ctx, output, fmt):
+    """Record wrightty actions as a replayable script. Press Ctrl+C to stop."""
+    ext = {"python": ".py", "json": ".json", "cli": ".sh"}[fmt]
+    output = output or f"recording{ext}"
+    term = _connect(ctx)
+    try:
+        rec_id = term.start_action_recording(format=fmt)
+        click.echo(f"Recording actions... (press Ctrl+C to stop, saving to {output})")
+        try:
+            import signal
+            signal.pause()
+        except KeyboardInterrupt:
+            pass
+        result = term.stop_action_recording(rec_id)
+        with open(output, "w") as f:
+            f.write(result["data"] if isinstance(result["data"], str) else json.dumps(result["data"], indent=2))
+        click.echo(f"Saved {result['actions']} actions, {result['duration']:.1f}s to {output}")
+    finally:
+        term.close()
+
+
+if __name__ == "__main__":
+    main()

wrightty-0.1.0/wrightty/client.py

@@ -0,0 +1,136 @@
+"""Low-level WebSocket JSON-RPC client for the Wrightty protocol.
+
+Uses a raw socket WebSocket implementation to avoid version issues
+with the `websockets` library. Zero external dependencies.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import socket
+import struct
+from typing import Any
+from urllib.parse import urlparse
+
+
+class WrighttyClient:
+    """Raw JSON-RPC client over WebSocket. No async, no dependencies."""
+
+    def __init__(self, sock: socket.socket):
+        self._sock = sock
+        self._next_id = 1
+
+    @classmethod
+    def connect(cls, url: str = "ws://127.0.0.1:9420") -> WrighttyClient:
+        parsed = urlparse(url)
+        host = parsed.hostname or "127.0.0.1"
+        port = parsed.port or 9420
+
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.connect((host, port))
+        sock.settimeout(30)
+
+        # WebSocket handshake.
+        key = base64.b64encode(os.urandom(16)).decode()
+        request = (
+            f"GET / HTTP/1.1\r\n"
+            f"Host: {host}:{port}\r\n"
+            f"Connection: Upgrade\r\n"
+            f"Upgrade: websocket\r\n"
+            f"Sec-WebSocket-Version: 13\r\n"
+            f"Sec-WebSocket-Key: {key}\r\n"
+            f"\r\n"
+        )
+        sock.sendall(request.encode())
+
+        # Read response headers.
+        response = b""
+        while b"\r\n\r\n" not in response:
+            response += sock.recv(4096)
+
+        if b"101" not in response:
+            raise ConnectionError(f"WebSocket handshake failed: {response.decode()}")
+
+        return cls(sock)
+
+    def close(self):
+        try:
+            self._sock.close()
+        except Exception:
+            pass
+
+    def request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        req_id = self._next_id
+        self._next_id += 1
+
+        msg = {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params or {}}
+        self._send_frame(json.dumps(msg))
+        raw = self._recv_frame()
+        resp = json.loads(raw)
+
+        if "error" in resp:
+            err = resp["error"]
+            raise WrighttyError(err.get("code", -1), err.get("message", "Unknown error"))
+
+        return resp.get("result")
+
+    def _send_frame(self, msg: str):
+        """Send a masked WebSocket text frame."""
+        payload = msg.encode()
+        mask = os.urandom(4)
+        frame = bytearray([0x81])  # FIN + text opcode
+
+        length = len(payload)
+        if length < 126:
+            frame.append(0x80 | length)
+        elif length < 65536:
+            frame.append(0x80 | 126)
+            frame.extend(struct.pack(">H", length))
+        else:
+            frame.append(0x80 | 127)
+            frame.extend(struct.pack(">Q", length))
+
+        frame.extend(mask)
+        for i, b in enumerate(payload):
+            frame.append(b ^ mask[i % 4])
+        self._sock.sendall(bytes(frame))
+
+    def _recv_frame(self) -> str:
+        """Receive a WebSocket text frame."""
+        header = self._recv_exact(2)
+        length = header[1] & 0x7F
+
+        if length == 126:
+            length = struct.unpack(">H", self._recv_exact(2))[0]
+        elif length == 127:
+            length = struct.unpack(">Q", self._recv_exact(8))[0]
+
+        # Server frames are not masked.
+        payload = self._recv_exact(length)
+        return payload.decode()
+
+    def _recv_exact(self, n: int) -> bytes:
+        """Read exactly n bytes."""
+        data = b""
+        while len(data) < n:
+            chunk = self._sock.recv(n - len(data))
+            if not chunk:
+                raise ConnectionError("Connection closed")
+            data += chunk
+        return data
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class WrighttyError(Exception):
+    def __init__(self, code: int, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")