@moejay/wrightty 0.0.0

package/sdks/node/src/terminal.ts

@@ -0,0 +1,258 @@
+/** High-level Terminal API for AI agents and automation. */
+
+import { WrighttyClient } from "./client";
+import type {
+  ConnectOptions,
+  DiscoveredServer,
+  ScreenshotFormat,
+  ScreenshotResult,
+  SessionInfo,
+  SpawnOptions,
+  WaitForTextResult,
+  SessionRecordingData,
+  ActionRecordingData,
+} from "./types";
+
+const PORT_RANGE_START = 9420;
+const PORT_RANGE_END = 9520;
+
+export class Terminal {
+  private client: WrighttyClient;
+  private sessionId: string;
+  private promptPattern = /[$#>%]\s*$/;
+
+  private constructor(client: WrighttyClient, sessionId: string) {
+    this.client = client;
+    this.sessionId = sessionId;
+  }
+
+  /** Scan for running wrightty servers on ports 9420-9520. */
+  static async discover(host = "127.0.0.1"): Promise<DiscoveredServer[]> {
+    const found: DiscoveredServer[] = [];
+
+    const checks = [];
+    for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+      const url = `ws://${host}:${port}`;
+      checks.push(
+        WrighttyClient.connect(url, 200)
+          .then(async (client) => {
+            try {
+              const info = await client.request("Wrightty.getInfo");
+              found.push({
+                url,
+                port,
+                version: info.version ?? "unknown",
+                implementation: info.implementation ?? "unknown",
+                capabilities: info.capabilities ?? {},
+              });
+            } finally {
+              client.close();
+            }
+          })
+          .catch(() => {
+            /* port not listening */
+          }),
+      );
+    }
+
+    await Promise.all(checks);
+    return found.sort((a, b) => a.port - b.port);
+  }
+
+  /** Connect to a wrightty server. Auto-discovers if no URL given. */
+  static async connect(options: ConnectOptions = {}): Promise<Terminal> {
+    let url = options.url;
+
+    if (!url) {
+      const servers = await Terminal.discover();
+      if (servers.length === 0) {
+        throw new Error(
+          "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;
+    }
+
+    const client = await WrighttyClient.connect(url, options.timeout ?? 5000);
+
+    let sessionId = options.sessionId;
+    if (!sessionId) {
+      const result = await client.request("Session.list");
+      const sessions: SessionInfo[] = result.sessions ?? [];
+      sessionId = sessions.length > 0 ? sessions[0].sessionId : "0";
+    }
+
+    return new Terminal(client, sessionId);
+  }
+
+  /** Connect to a headless server and create a new session. */
+  static async spawn(options: SpawnOptions = {}): Promise<Terminal> {
+    const url = options.serverUrl ?? "ws://127.0.0.1:9420";
+    const client = await WrighttyClient.connect(url);
+
+    const result = await client.request("Session.create", {
+      cols: options.cols ?? 120,
+      rows: options.rows ?? 40,
+      shell: options.shell,
+      cwd: options.cwd,
+    });
+
+    const term = new Terminal(client, result.sessionId);
+    await term.waitForPrompt(5000);
+    return term;
+  }
+
+  /** Close the connection. */
+  close(): void {
+    this.client.close();
+  }
+
+  // --- High-level API ---
+
+  /** Run a command and return its output. */
+  async run(command: string, timeoutMs = 30000): Promise<string> {
+    await this.sendText(command + "\n");
+    await this.waitForPrompt(timeoutMs);
+
+    const screen = await this.readScreen();
+    const lines = screen.trim().split("\n");
+
+    const outputLines: string[] = [];
+    let foundCmd = false;
+    for (const line of lines) {
+      if (!foundCmd) {
+        if (line.includes(command)) foundCmd = true;
+        continue;
+      }
+      if (this.promptPattern.test(line)) break;
+      outputLines.push(line);
+    }
+
+    return outputLines.join("\n");
+  }
+
+  /** Send raw text to the terminal. */
+  async sendText(text: string): Promise<void> {
+    await this.client.request("Input.sendText", {
+      sessionId: this.sessionId,
+      text,
+    });
+  }
+
+  /** Send structured keystrokes. */
+  async sendKeys(...keys: string[]): Promise<void> {
+    await this.client.request("Input.sendKeys", {
+      sessionId: this.sessionId,
+      keys,
+    });
+  }
+
+  /** Read the current visible screen as text. */
+  async readScreen(): Promise<string> {
+    const result = await this.client.request("Screen.getText", {
+      sessionId: this.sessionId,
+    });
+    return result.text;
+  }
+
+  /** Take a screenshot. */
+  async screenshot(format: ScreenshotFormat = "svg"): Promise<ScreenshotResult> {
+    return this.client.request("Screen.screenshot", {
+      sessionId: this.sessionId,
+      format,
+    });
+  }
+
+  /** Wait until a pattern appears on screen. */
+  async waitFor(pattern: string | RegExp, timeoutMs = 30000): Promise<string> {
+    const isRegex = pattern instanceof RegExp;
+    const patternStr = isRegex ? pattern.source : pattern;
+
+    const result: WaitForTextResult = await this.client.request("Screen.waitForText", {
+      sessionId: this.sessionId,
+      pattern: patternStr,
+      isRegex,
+      timeout: timeoutMs,
+      interval: 50,
+    });
+
+    if (!result.found) {
+      throw new Error(`Pattern ${patternStr} not found within ${timeoutMs}ms`);
+    }
+
+    return this.readScreen();
+  }
+
+  /** Wait for the shell prompt to appear. */
+  async waitForPrompt(timeoutMs = 10000): Promise<string> {
+    return this.waitFor(this.promptPattern, timeoutMs);
+  }
+
+  /** Override the regex used to detect the shell prompt. */
+  setPromptPattern(pattern: RegExp): void {
+    this.promptPattern = pattern;
+  }
+
+  /** Get terminal dimensions as [cols, rows]. */
+  async getSize(): Promise<[number, number]> {
+    const result = await this.client.request("Terminal.getSize", {
+      sessionId: this.sessionId,
+    });
+    return [result.cols, result.rows];
+  }
+
+  /** Resize the terminal. */
+  async resize(cols: number, rows: number): Promise<void> {
+    await this.client.request("Terminal.resize", {
+      sessionId: this.sessionId,
+      cols,
+      rows,
+    });
+  }
+
+  /** Get server info and capabilities. */
+  async getInfo(): Promise<Record<string, any>> {
+    return this.client.request("Wrightty.getInfo");
+  }
+
+  // --- Recording ---
+
+  /** Start recording raw PTY I/O (asciicast v2 format). */
+  async startSessionRecording(includeInput = false): Promise<string> {
+    const result = await this.client.request("Recording.startSession", {
+      sessionId: this.sessionId,
+      includeInput,
+    });
+    return result.recordingId;
+  }
+
+  /** Stop a session recording and return asciicast data. */
+  async stopSessionRecording(recordingId: string): Promise<SessionRecordingData> {
+    return this.client.request("Recording.stopSession", { recordingId });
+  }
+
+  /** Start recording wrightty API calls as a replayable script. */
+  async startActionRecording(format: "python" | "json" | "cli" = "python"): Promise<string> {
+    const result = await this.client.request("Recording.startActions", {
+      sessionId: this.sessionId,
+      format,
+    });
+    return result.recordingId;
+  }
+
+  /** Stop action recording and return the generated script. */
+  async stopActionRecording(recordingId: string): Promise<ActionRecordingData> {
+    return this.client.request("Recording.stopActions", { recordingId });
+  }
+
+  /** Capture a single screen frame. */
+  async captureScreen(format: ScreenshotFormat = "svg"): Promise<Record<string, any>> {
+    return this.client.request("Recording.captureScreen", {
+      sessionId: this.sessionId,
+      format,
+    });
+  }
+}

package/sdks/node/src/types.ts

@@ -0,0 +1,105 @@
+/** Wrightty protocol types — mirrors wrightty-protocol Rust crate. */
+
+export interface ServerInfo {
+  version: string;
+  implementation: string;
+  capabilities: Capabilities;
+}
+
+export interface Capabilities {
+  screenshot: ScreenshotFormat[];
+  maxSessions: number;
+  supportsResize: boolean;
+  supportsScrollback: boolean;
+  supportsMouse: boolean;
+  supportsSessionCreate: boolean;
+  supportsColorPalette: boolean;
+  supportsRawOutput: boolean;
+  supportsShellIntegration: boolean;
+  events: string[];
+}
+
+export type ScreenshotFormat = "text" | "svg" | "png" | "json";
+
+export interface SessionInfo {
+  sessionId: string;
+  title: string;
+  cwd?: string;
+  cols: number;
+  rows: number;
+  pid?: number;
+  running: boolean;
+  alternateScreen: boolean;
+}
+
+export type KeyInput = string | KeyEvent;
+
+export interface KeyEvent {
+  key: string;
+  char?: string;
+  n?: number;
+  modifiers: string[];
+}
+
+export interface TextMatch {
+  text: string;
+  row: number;
+  col: number;
+  length: number;
+}
+
+export interface WaitForTextResult {
+  found: boolean;
+  matches: TextMatch[];
+  elapsed: number;
+}
+
+export interface ScreenshotResult {
+  format: ScreenshotFormat;
+  data: string;
+  width?: number;
+  height?: number;
+}
+
+export interface RecordingResult {
+  recordingId: string;
+}
+
+export interface SessionRecordingData {
+  format: string;
+  data: string;
+  duration: number;
+  events: number;
+}
+
+export interface ActionRecordingData {
+  format: string;
+  data: string;
+  actions: number;
+  duration: number;
+}
+
+export interface DiscoveredServer {
+  url: string;
+  port: number;
+  version: string;
+  implementation: string;
+  capabilities: Capabilities;
+}
+
+export interface ConnectOptions {
+  /** Server URL (default: auto-discover) */
+  url?: string;
+  /** Session ID (default: first available) */
+  sessionId?: string;
+  /** Connection timeout in ms (default: 5000) */
+  timeout?: number;
+}
+
+export interface SpawnOptions {
+  shell?: string;
+  cols?: number;
+  rows?: number;
+  cwd?: string;
+  serverUrl?: string;
+}

package/sdks/node/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/sdks/python/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

package/sdks/python/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"

package/sdks/python/wrightty/__init__.py

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