@moejay/wrightty 0.0.0 → 0.1.1

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** wrightty CLI for Node.js — control terminals from the command line. */
+export {};

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+"use strict";
+/** wrightty CLI for Node.js — control terminals from the command line. */
+Object.defineProperty(exports, "__esModule", { value: true });
+const terminal_1 = require("./terminal");
+const args = process.argv.slice(2);
+const command = args[0];
+function usage() {
+    console.log(`wrightty-js — Playwright for terminals (Node.js)
+
+Usage:
+  wrightty-js run <command> [--timeout <s>]   Run a command and print output
+  wrightty-js read                            Read the terminal screen
+  wrightty-js send-text <text>                Send raw text
+  wrightty-js send-keys <key> [<key>...]      Send keystrokes
+  wrightty-js screenshot [--format svg|text]  Take a screenshot
+  wrightty-js wait-for <pattern> [--timeout]  Wait for text on screen
+  wrightty-js info                            Show server info
+  wrightty-js size                            Get terminal dimensions
+  wrightty-js discover                        Find running servers
+
+Options:
+  --url <url>         Server URL (default: auto-discover)
+  --session <id>      Session ID (default: first available)
+  --help              Show this help`);
+}
+function getOpt(name) {
+    const idx = args.indexOf(name);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+function hasFlag(name) {
+    return args.includes(name);
+}
+async function getTerminal() {
+    const url = getOpt("--url");
+    const sessionId = getOpt("--session");
+    return terminal_1.Terminal.connect({ url, sessionId });
+}
+async function main() {
+    if (!command || hasFlag("--help") || hasFlag("-h")) {
+        usage();
+        process.exit(0);
+    }
+    try {
+        switch (command) {
+            case "discover": {
+                const servers = await terminal_1.Terminal.discover();
+                if (servers.length === 0) {
+                    console.log("No wrightty servers found.");
+                }
+                else {
+                    for (const s of servers) {
+                        console.log(`  ${s.url}  ${s.implementation} v${s.version}`);
+                    }
+                }
+                break;
+            }
+            case "run": {
+                const cmd = args[1];
+                if (!cmd) {
+                    console.error("Usage: wrightty-js run <command>");
+                    process.exit(1);
+                }
+                const timeout = parseInt(getOpt("--timeout") ?? "30", 10) * 1000;
+                const term = await getTerminal();
+                const output = await term.run(cmd, timeout);
+                console.log(output);
+                term.close();
+                break;
+            }
+            case "read": {
+                const term = await getTerminal();
+                console.log(await term.readScreen());
+                term.close();
+                break;
+            }
+            case "send-text": {
+                const text = args[1];
+                if (!text) {
+                    console.error("Usage: wrightty-js send-text <text>");
+                    process.exit(1);
+                }
+                const term = await getTerminal();
+                await term.sendText(text.replace(/\\n/g, "\n"));
+                term.close();
+                break;
+            }
+            case "send-keys": {
+                const keys = args.slice(1).filter(k => !k.startsWith("--"));
+                if (keys.length === 0) {
+                    console.error("Usage: wrightty-js send-keys <key> [...]");
+                    process.exit(1);
+                }
+                const term = await getTerminal();
+                await term.sendKeys(...keys);
+                term.close();
+                break;
+            }
+            case "screenshot": {
+                const format = (getOpt("--format") ?? "text");
+                const term = await getTerminal();
+                const result = await term.screenshot(format);
+                console.log(result.data);
+                term.close();
+                break;
+            }
+            case "wait-for": {
+                const pattern = args[1];
+                if (!pattern) {
+                    console.error("Usage: wrightty-js wait-for <pattern>");
+                    process.exit(1);
+                }
+                const timeout = parseInt(getOpt("--timeout") ?? "30", 10) * 1000;
+                const term = await getTerminal();
+                const screen = await term.waitFor(pattern, timeout);
+                console.log(screen);
+                term.close();
+                break;
+            }
+            case "info": {
+                const term = await getTerminal();
+                console.log(JSON.stringify(await term.getInfo(), null, 2));
+                term.close();
+                break;
+            }
+            case "size": {
+                const term = await getTerminal();
+                const [cols, rows] = await term.getSize();
+                console.log(`${cols}x${rows}`);
+                term.close();
+                break;
+            }
+            default:
+                console.error(`Unknown command: ${command}`);
+                usage();
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+main();

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+/** Low-level WebSocket JSON-RPC 2.0 client for the Wrightty protocol. */
+export declare class WrighttyError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+}
+export declare class WrighttyClient {
+    private ws;
+    private nextId;
+    private pending;
+    private constructor();
+    static connect(url: string, timeoutMs?: number): Promise<WrighttyClient>;
+    request(method: string, params?: Record<string, any>): Promise<any>;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,83 @@
+"use strict";
+/** Low-level WebSocket JSON-RPC 2.0 client for the Wrightty protocol. */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrighttyClient = exports.WrighttyError = void 0;
+const ws_1 = __importDefault(require("ws"));
+class WrighttyError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.code = code;
+        this.name = "WrighttyError";
+    }
+}
+exports.WrighttyError = WrighttyError;
+class WrighttyClient {
+    ws;
+    nextId = 1;
+    pending = new Map();
+    constructor(ws) {
+        this.ws = ws;
+        ws.on("message", (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, timeoutMs = 5000) {
+        return new Promise((resolve, reject) => {
+            const ws = new ws_1.default(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, params = {}) {
+        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() {
+        this.ws.close();
+    }
+}
+exports.WrighttyClient = WrighttyClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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";

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrighttyError = exports.WrighttyClient = exports.Terminal = void 0;
+var terminal_1 = require("./terminal");
+Object.defineProperty(exports, "Terminal", { enumerable: true, get: function () { return terminal_1.Terminal; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "WrighttyClient", { enumerable: true, get: function () { return client_1.WrighttyClient; } });
+Object.defineProperty(exports, "WrighttyError", { enumerable: true, get: function () { return client_1.WrighttyError; } });

package/dist/terminal.d.ts

@@ -0,0 +1,48 @@
+/** High-level Terminal API for AI agents and automation. */
+import type { ConnectOptions, DiscoveredServer, ScreenshotFormat, ScreenshotResult, SpawnOptions, SessionRecordingData, ActionRecordingData } from "./types";
+export declare class Terminal {
+    private client;
+    private sessionId;
+    private promptPattern;
+    private constructor();
+    /** Scan for running wrightty servers on ports 9420-9520. */
+    static discover(host?: string): Promise<DiscoveredServer[]>;
+    /** Connect to a wrightty server. Auto-discovers if no URL given. */
+    static connect(options?: ConnectOptions): Promise<Terminal>;
+    /** Connect to a headless server and create a new session. */
+    static spawn(options?: SpawnOptions): Promise<Terminal>;
+    /** Close the connection. */
+    close(): void;
+    /** Run a command and return its output. */
+    run(command: string, timeoutMs?: number): Promise<string>;
+    /** Send raw text to the terminal. */
+    sendText(text: string): Promise<void>;
+    /** Send structured keystrokes. */
+    sendKeys(...keys: string[]): Promise<void>;
+    /** Read the current visible screen as text. */
+    readScreen(): Promise<string>;
+    /** Take a screenshot. */
+    screenshot(format?: ScreenshotFormat): Promise<ScreenshotResult>;
+    /** Wait until a pattern appears on screen. */
+    waitFor(pattern: string | RegExp, timeoutMs?: number): Promise<string>;
+    /** Wait for the shell prompt to appear. */
+    waitForPrompt(timeoutMs?: number): Promise<string>;
+    /** Override the regex used to detect the shell prompt. */
+    setPromptPattern(pattern: RegExp): void;
+    /** Get terminal dimensions as [cols, rows]. */
+    getSize(): Promise<[number, number]>;
+    /** Resize the terminal. */
+    resize(cols: number, rows: number): Promise<void>;
+    /** Get server info and capabilities. */
+    getInfo(): Promise<Record<string, any>>;
+    /** Start recording raw PTY I/O (asciicast v2 format). */
+    startSessionRecording(includeInput?: boolean): Promise<string>;
+    /** Stop a session recording and return asciicast data. */
+    stopSessionRecording(recordingId: string): Promise<SessionRecordingData>;
+    /** Start recording wrightty API calls as a replayable script. */
+    startActionRecording(format?: "python" | "json" | "cli"): Promise<string>;
+    /** Stop action recording and return the generated script. */
+    stopActionRecording(recordingId: string): Promise<ActionRecordingData>;
+    /** Capture a single screen frame. */
+    captureScreen(format?: ScreenshotFormat): Promise<Record<string, any>>;
+}

package/dist/terminal.js

@@ -0,0 +1,210 @@
+"use strict";
+/** High-level Terminal API for AI agents and automation. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Terminal = void 0;
+const client_1 = require("./client");
+const PORT_RANGE_START = 9420;
+const PORT_RANGE_END = 9520;
+class Terminal {
+    client;
+    sessionId;
+    promptPattern = /[$#>%]\s*$/;
+    constructor(client, sessionId) {
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+    /** Scan for running wrightty servers on ports 9420-9520. */
+    static async discover(host = "127.0.0.1") {
+        const found = [];
+        const checks = [];
+        for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+            const url = `ws://${host}:${port}`;
+            checks.push(client_1.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 = {}) {
+        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 client_1.WrighttyClient.connect(url, options.timeout ?? 5000);
+        let sessionId = options.sessionId;
+        if (!sessionId) {
+            const result = await client.request("Session.list");
+            const sessions = 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 = {}) {
+        const url = options.serverUrl ?? "ws://127.0.0.1:9420";
+        const client = await client_1.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() {
+        this.client.close();
+    }
+    // --- High-level API ---
+    /** Run a command and return its output. */
+    async run(command, timeoutMs = 30000) {
+        await this.sendText(command + "\n");
+        await this.waitForPrompt(timeoutMs);
+        const screen = await this.readScreen();
+        const lines = screen.trim().split("\n");
+        const outputLines = [];
+        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) {
+        await this.client.request("Input.sendText", {
+            sessionId: this.sessionId,
+            text,
+        });
+    }
+    /** Send structured keystrokes. */
+    async sendKeys(...keys) {
+        await this.client.request("Input.sendKeys", {
+            sessionId: this.sessionId,
+            keys,
+        });
+    }
+    /** Read the current visible screen as text. */
+    async readScreen() {
+        const result = await this.client.request("Screen.getText", {
+            sessionId: this.sessionId,
+        });
+        return result.text;
+    }
+    /** Take a screenshot. */
+    async screenshot(format = "svg") {
+        return this.client.request("Screen.screenshot", {
+            sessionId: this.sessionId,
+            format,
+        });
+    }
+    /** Wait until a pattern appears on screen. */
+    async waitFor(pattern, timeoutMs = 30000) {
+        const isRegex = pattern instanceof RegExp;
+        const patternStr = isRegex ? pattern.source : pattern;
+        const result = 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) {
+        return this.waitFor(this.promptPattern, timeoutMs);
+    }
+    /** Override the regex used to detect the shell prompt. */
+    setPromptPattern(pattern) {
+        this.promptPattern = pattern;
+    }
+    /** Get terminal dimensions as [cols, rows]. */
+    async getSize() {
+        const result = await this.client.request("Terminal.getSize", {
+            sessionId: this.sessionId,
+        });
+        return [result.cols, result.rows];
+    }
+    /** Resize the terminal. */
+    async resize(cols, rows) {
+        await this.client.request("Terminal.resize", {
+            sessionId: this.sessionId,
+            cols,
+            rows,
+        });
+    }
+    /** Get server info and capabilities. */
+    async getInfo() {
+        return this.client.request("Wrightty.getInfo");
+    }
+    // --- Recording ---
+    /** Start recording raw PTY I/O (asciicast v2 format). */
+    async startSessionRecording(includeInput = false) {
+        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) {
+        return this.client.request("Recording.stopSession", { recordingId });
+    }
+    /** Start recording wrightty API calls as a replayable script. */
+    async startActionRecording(format = "python") {
+        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) {
+        return this.client.request("Recording.stopActions", { recordingId });
+    }
+    /** Capture a single screen frame. */
+    async captureScreen(format = "svg") {
+        return this.client.request("Recording.captureScreen", {
+            sessionId: this.sessionId,
+            format,
+        });
+    }
+}
+exports.Terminal = Terminal;

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+/** 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/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Wrightty protocol types — mirrors wrightty-protocol Rust crate. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,24 +1,47 @@
 {
   "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"
-  },
+  "version": "0.1.1",
+  "description": "Node.js SDK for Wrightty terminal automation protocol",
+  "author": "Moe Jay",
+  "homepage": "https://github.com/moejay/wrightty",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/moejay/wrightty.git"
+    "url": "https://github.com/moejay/wrightty.git",
+    "directory": "sdks/node"
   },
-  "license": "ISC",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
-  "directories": {
-    "example": "examples",
-    "test": "tests"
+  "bugs": {
+    "url": "https://github.com/moejay/wrightty/issues"
   },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "wrightty-js": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "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"
   }
 }