@moejay/wrightty 0.0.0

package/examples/record_session.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""record_session.py -- Start a session recording, run commands, save the asciicast file.
+
+Demonstrates Wrightty's recording capabilities:
+  - Session recording produces an asciicast v2 (.cast) file
+  - Compatible with `asciinema play` for playback and sharing
+
+Usage:
+    python examples/record_session.py
+
+Prerequisites:
+    - wrightty-server running on ws://127.0.0.1:9420
+      Start with: cargo run -p wrightty-server
+
+    - Python SDK installed (from repo root):
+      pip install -e sdks/python
+
+    - Optional: asciinema installed to play back the recording
+      pip install asciinema   or   brew install asciinema
+"""
+
+import json
+import os
+
+from wrightty import Terminal
+
+OUTPUT_PATH = "/tmp/wrightty_demo.cast"
+
+
+def main():
+    print("Spawning terminal session...")
+
+    with Terminal.spawn(cols=100, rows=30) as term:
+        info = term.get_info()
+        print(f"Connected to {info['implementation']} v{info['version']}")
+        print()
+
+        # --- Start session recording ---
+        print("Starting session recording...")
+        recording_id = term.start_session_recording(include_input=False)
+        print(f"Recording ID: {recording_id}")
+        print()
+
+        # --- Run some commands while recording ---
+        print("Running commands (these will be captured in the recording)...")
+
+        output = term.run("echo 'Hello from Wrightty!'")
+        print(f"  echo output: {output.strip()}")
+
+        output = term.run("date")
+        print(f"  date output: {output.strip()}")
+
+        output = term.run("uname -s")
+        print(f"  uname output: {output.strip()}")
+
+        output = term.run("echo 'Recording complete.'")
+        print(f"  final echo: {output.strip()}")
+        print()
+
+        # --- Stop the recording ---
+        print("Stopping recording...")
+        result = term.stop_session_recording(recording_id)
+
+        asciicast_data = result["data"]
+        duration = result.get("duration", 0)
+        event_count = result.get("events", 0)
+
+        print(f"Recorded {event_count} events over {duration:.1f}s")
+        print()
+
+        # --- Save the asciicast file ---
+        with open(OUTPUT_PATH, "w") as f:
+            f.write(asciicast_data)
+
+        file_size = os.path.getsize(OUTPUT_PATH)
+        print(f"Saved asciicast to {OUTPUT_PATH} ({file_size} bytes)")
+        print()
+
+        # Show the asciicast header so the user can inspect it
+        lines = asciicast_data.splitlines()
+        if lines:
+            header = json.loads(lines[0])
+            print("Asciicast header:")
+            print(f"  version: {header.get('version')}")
+            print(f"  width:   {header.get('width')}")
+            print(f"  height:  {header.get('height')}")
+            if "title" in header:
+                print(f"  title:   {header['title']}")
+        print()
+
+    print(f"Done. To play back the recording:")
+    print(f"  asciinema play {OUTPUT_PATH}")
+
+
+if __name__ == "__main__":
+    main()

package/install.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# Install wrightty — terminal automation CLI
+# Usage: curl -fsSL https://raw.githubusercontent.com/moejay/wrightty/main/install.sh | sh
+set -e
+
+REPO="moejay/wrightty"
+INSTALL_DIR="${WRIGHTTY_INSTALL_DIR:-/usr/local/bin}"
+
+# Detect OS and architecture
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  Linux)  OS_NAME="linux" ;;
+  Darwin) OS_NAME="macos" ;;
+  *)
+    echo "error: Unsupported OS: $OS"
+    echo "Build from source: cargo install --git https://github.com/$REPO wrightty"
+    exit 1
+    ;;
+esac
+
+case "$ARCH" in
+  x86_64|amd64)  ARCH_NAME="x86_64" ;;
+  aarch64|arm64) ARCH_NAME="aarch64" ;;
+  *)
+    echo "error: Unsupported architecture: $ARCH"
+    echo "Build from source: cargo install --git https://github.com/$REPO wrightty"
+    exit 1
+    ;;
+esac
+
+ASSET_NAME="wrightty-${OS_NAME}-${ARCH_NAME}"
+
+# Get latest release URL
+if [ -n "$WRIGHTTY_VERSION" ]; then
+  TAG="v${WRIGHTTY_VERSION}"
+  URL="https://github.com/$REPO/releases/download/$TAG/${ASSET_NAME}.tar.gz"
+else
+  URL="https://github.com/$REPO/releases/latest/download/${ASSET_NAME}.tar.gz"
+fi
+
+echo "Downloading wrightty for ${OS_NAME}/${ARCH_NAME}..."
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+if command -v curl >/dev/null 2>&1; then
+  curl -fsSL "$URL" -o "$TMPDIR/wrightty.tar.gz"
+elif command -v wget >/dev/null 2>&1; then
+  wget -q "$URL" -O "$TMPDIR/wrightty.tar.gz"
+else
+  echo "error: curl or wget required"
+  exit 1
+fi
+
+tar xzf "$TMPDIR/wrightty.tar.gz" -C "$TMPDIR"
+
+# Install
+if [ -w "$INSTALL_DIR" ]; then
+  mv "$TMPDIR/wrightty" "$INSTALL_DIR/wrightty"
+else
+  echo "Installing to $INSTALL_DIR (requires sudo)..."
+  sudo mv "$TMPDIR/wrightty" "$INSTALL_DIR/wrightty"
+fi
+
+chmod +x "$INSTALL_DIR/wrightty"
+
+echo ""
+echo "wrightty installed to $INSTALL_DIR/wrightty"
+echo ""
+echo "Get started:"
+echo "  wrightty term --headless        # start a headless terminal server"
+echo "  wrightty run \"echo hello\"       # run a command"
+echo "  wrightty discover               # find running servers"
+echo ""
+echo "Or bridge to your terminal:"
+echo "  wrightty term --bridge-tmux     # if you use tmux"
+echo "  wrightty term --bridge-wezterm  # if you use WezTerm"
+echo "  wrightty term --bridge-kitty    # if you use Kitty"
+echo "  wrightty term --bridge-ghostty  # if you use Ghostty"
+echo "  wrightty term --bridge-zellij   # if you use Zellij"

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@moejay/wrightty",
+  "version": "0.0.0",
+  "description": "[![CI](https://github.com/moejay/wrightty/actions/workflows/ci.yml/badge.svg)](https://github.com/moejay/wrightty/actions/workflows/ci.yml) [![Release](https://github.com/moejay/wrightty/actions/workflows/release.yml/badge.svg)](https://github.com/moejay/wrightty/actions/workflows/release.yml) [![crates.io](https://img.shields.io/crates/v/wrightty.svg)](https://crates.io/crates/wrightty) [![PyPI](https://img.shields.io/pypi/v/wrightty.svg)](https://pypi.org/project/wrightty/) [![npm](https://img.shields.io/npm/v/@moejay/wrightty.svg)](https://www.npmjs.com/package/@moejay/wrightty) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)",
+  "homepage": "https://github.com/moejay/wrightty#readme",
+  "bugs": {
+    "url": "https://github.com/moejay/wrightty/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moejay/wrightty.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "index.js",
+  "directories": {
+    "example": "examples",
+    "test": "tests"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/sdks/node/package-lock.json

@@ -0,0 +1,85 @@
+{
+  "name": "wrightty",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "wrightty",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "ws": "^8.0.0"
+      },
+      "devDependencies": {
+        "@types/ws": "^8.0.0",
+        "typescript": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "25.5.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.2.tgz",
+      "integrity": "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ws": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
+      "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

package/sdks/node/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@moejay/wrightty",
+  "version": "0.1.0",
+  "description": "Node.js SDK for Wrightty terminal automation protocol",
+  "author": "Moe Jay",
+  "homepage": "https://github.com/moejay/wrightty",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moejay/wrightty.git",
+    "directory": "sdks/node"
+  },
+  "bugs": {
+    "url": "https://github.com/moejay/wrightty/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "terminal",
+    "automation",
+    "tui",
+    "playwright",
+    "testing",
+    "ai",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/sdks/node/src/client.ts

@@ -0,0 +1,94 @@
+/** Low-level WebSocket JSON-RPC 2.0 client for the Wrightty protocol. */
+
+import WebSocket from "ws";
+
+export class WrighttyError extends Error {
+  constructor(
+    public code: number,
+    message: string,
+  ) {
+    super(`[${code}] ${message}`);
+    this.name = "WrighttyError";
+  }
+}
+
+export class WrighttyClient {
+  private ws: WebSocket;
+  private nextId = 1;
+  private pending = new Map<
+    number,
+    {
+      resolve: (value: any) => void;
+      reject: (reason: any) => void;
+    }
+  >();
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+
+    ws.on("message", (data: WebSocket.Data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        const entry = this.pending.get(msg.id);
+        if (!entry) return;
+        this.pending.delete(msg.id);
+
+        if (msg.error) {
+          entry.reject(
+            new WrighttyError(msg.error.code ?? -1, msg.error.message ?? "Unknown error"),
+          );
+        } else {
+          entry.resolve(msg.result);
+        }
+      } catch {
+        // Ignore malformed messages
+      }
+    });
+
+    ws.on("close", () => {
+      for (const [id, entry] of this.pending) {
+        entry.reject(new Error("Connection closed"));
+        this.pending.delete(id);
+      }
+    });
+  }
+
+  static connect(url: string, timeoutMs = 5000): Promise<WrighttyClient> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+      const timer = setTimeout(() => {
+        ws.close();
+        reject(new Error(`Connection timeout after ${timeoutMs}ms: ${url}`));
+      }, timeoutMs);
+
+      ws.on("open", () => {
+        clearTimeout(timer);
+        resolve(new WrighttyClient(ws));
+      });
+
+      ws.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
+
+  async request(method: string, params: Record<string, any> = {}): Promise<any> {
+    const id = this.nextId++;
+    const msg = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(msg, (err) => {
+        if (err) {
+          this.pending.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  close(): void {
+    this.ws.close();
+  }
+}

package/sdks/node/src/index.ts

@@ -0,0 +1,19 @@
+export { Terminal } from "./terminal";
+export { WrighttyClient, WrighttyError } from "./client";
+export type {
+  ServerInfo,
+  Capabilities,
+  ScreenshotFormat,
+  SessionInfo,
+  KeyInput,
+  KeyEvent,
+  TextMatch,
+  WaitForTextResult,
+  ScreenshotResult,
+  RecordingResult,
+  SessionRecordingData,
+  ActionRecordingData,
+  DiscoveredServer,
+  ConnectOptions,
+  SpawnOptions,
+} from "./types";