cmux 0.3.6 → 0.4.0

package/dist/src/websocket-transport.d.ts

@@ -0,0 +1,75 @@
+import type { Transport, Unsubscribe } from "./transport.js";
+interface WebSocketEventMap {
+    open: unknown;
+    message: {
+        data: unknown;
+    };
+    close: {
+        code?: number;
+        reason?: string;
+    };
+    error: unknown;
+}
+/** The WebSocket subset used by `WebSocketTransport`. */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?<K extends keyof WebSocketEventMap>(type: K, listener: (event: WebSocketEventMap[K]) => void): void;
+    removeEventListener?<K extends keyof WebSocketEventMap>(type: K, listener: (event: WebSocketEventMap[K]) => void): void;
+    on?(type: string, listener: (...args: unknown[]) => void): void;
+    off?(type: string, listener: (...args: unknown[]) => void): void;
+}
+/** A browser- or Node-compatible WebSocket constructor. */
+export interface WebSocketConstructor {
+    new (url: string | URL, protocols?: string | string[]): WebSocketLike;
+}
+export interface WebSocketTransportOptions {
+    protocols?: string | string[];
+    /** Sends the cmux-tui WebSocket authentication preamble before queued protocol requests. */
+    authToken?: string;
+    /** Called while the server waits for a trusted TUI to approve this connection. */
+    onPairingChallenge?(challenge: PairingChallenge): void;
+    /** Receives the credential issued after approval for reconnects. */
+    onPairingCredential?(credential: string): void;
+    /** Called when a supplied token or reconnect credential is rejected. */
+    onAuthenticationRejected?(): void;
+    /** Inject a compatible constructor such as the Node `ws` package. */
+    WebSocket?: WebSocketConstructor;
+}
+export interface PairingChallenge {
+    id: number;
+    code: string;
+    peer: string;
+    expiresIn: number;
+}
+/** Sends and receives one JSON message per WebSocket text frame. */
+export declare class WebSocketTransport implements Transport {
+    private readonly socket;
+    private readonly pending;
+    private readonly messageHandlers;
+    private readonly closeHandlers;
+    private readonly errorHandlers;
+    private readonly authToken;
+    private readonly onPairingChallenge;
+    private readonly onPairingCredential;
+    private readonly onAuthenticationRejected;
+    private authenticated;
+    private closed;
+    constructor(url: string | URL, options?: WebSocketTransportOptions | WebSocketConstructor);
+    send(json: string): void;
+    onMessage(handler: (json: string) => void): Unsubscribe;
+    onClose(handler: () => void): Unsubscribe;
+    onError(handler: (error: Error) => void): Unsubscribe;
+    close(): void;
+    private globalConstructor;
+    private listen;
+    private flush;
+    private flushPending;
+    private receive;
+    private receivePairing;
+    private eventError;
+    private fail;
+    private finish;
+}
+export {};

package/dist/src/websocket-transport.js

@@ -0,0 +1,168 @@
+/** Sends and receives one JSON message per WebSocket text frame. */
+export class WebSocketTransport {
+    socket;
+    pending = [];
+    messageHandlers = new Set();
+    closeHandlers = new Set();
+    errorHandlers = new Set();
+    authToken;
+    onPairingChallenge;
+    onPairingCredential;
+    onAuthenticationRejected;
+    authenticated = false;
+    closed = false;
+    constructor(url, options = {}) {
+        const normalized = typeof options === "function" ? { WebSocket: options } : options;
+        const Constructor = normalized.WebSocket ?? this.globalConstructor();
+        this.authToken = normalized.authToken;
+        this.onPairingChallenge = normalized.onPairingChallenge;
+        this.onPairingCredential = normalized.onPairingCredential;
+        this.onAuthenticationRejected = normalized.onAuthenticationRejected;
+        this.socket = new Constructor(url, normalized.protocols);
+        this.listen("open", () => this.flush());
+        this.listen("message", (event) => this.receive(event));
+        this.listen("error", (event) => this.fail(this.eventError(event)));
+        this.listen("close", (event) => this.finish(event));
+    }
+    send(json) {
+        if (this.closed)
+            throw new Error("WebSocket transport is closed");
+        if (this.socket.readyState === 1 && this.authenticated)
+            this.socket.send(json);
+        else
+            this.pending.push(json);
+    }
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.add(handler);
+        if (this.closed)
+            queueMicrotask(handler);
+        return () => this.closeHandlers.delete(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.socket.close();
+    }
+    globalConstructor() {
+        const Constructor = globalThis.WebSocket;
+        if (!Constructor)
+            throw new Error("WebSocket is not available; inject a compatible constructor");
+        return Constructor;
+    }
+    listen(type, handler) {
+        if (this.socket.addEventListener) {
+            this.socket.addEventListener(type, handler);
+            return;
+        }
+        if (this.socket.on) {
+            this.socket.on(type, handler);
+            return;
+        }
+        throw new Error("injected WebSocket does not support event listeners");
+    }
+    flush() {
+        if (this.closed)
+            return;
+        if (this.authToken !== undefined) {
+            this.socket.send(JSON.stringify({ auth: { token: this.authToken } }));
+            this.authenticated = true;
+            this.flushPending();
+        }
+        else {
+            this.socket.send(JSON.stringify({ pair: { request: true } }));
+        }
+    }
+    flushPending() {
+        while (this.pending.length > 0)
+            this.socket.send(this.pending.shift());
+    }
+    receive(event) {
+        const data = event && typeof event === "object" && "data" in event ? event.data : event;
+        if (typeof data !== "string") {
+            this.fail(new Error("WebSocket server sent a non-text frame"));
+            return;
+        }
+        if (!this.authenticated) {
+            this.receivePairing(data);
+            return;
+        }
+        for (const handler of this.messageHandlers)
+            handler(data);
+    }
+    receivePairing(json) {
+        let value;
+        try {
+            value = JSON.parse(json);
+        }
+        catch {
+            this.fail(new Error("WebSocket server sent invalid pairing data"));
+            return;
+        }
+        if (!value || typeof value !== "object") {
+            this.fail(new Error("WebSocket server sent invalid pairing data"));
+            return;
+        }
+        const message = value;
+        if (message.pairing && typeof message.pairing === "object") {
+            const pairing = message.pairing;
+            if (typeof pairing.id === "number"
+                && typeof pairing.code === "string"
+                && typeof pairing.peer === "string"
+                && typeof pairing.expires_in === "number") {
+                this.onPairingChallenge?.({
+                    id: pairing.id,
+                    code: pairing.code,
+                    peer: pairing.peer,
+                    expiresIn: pairing.expires_in,
+                });
+                return;
+            }
+        }
+        if (message.paired && typeof message.paired === "object") {
+            const credential = message.paired.credential;
+            if (typeof credential === "string") {
+                this.authenticated = true;
+                this.onPairingCredential?.(credential);
+                this.flushPending();
+                return;
+            }
+        }
+        if (message.pairing_error && typeof message.pairing_error === "object") {
+            const pairingError = message.pairing_error;
+            this.fail(new Error(typeof pairingError.message === "string" ? pairingError.message : "Pairing failed"));
+            return;
+        }
+        this.fail(new Error("WebSocket server sent invalid pairing data"));
+    }
+    eventError(event) {
+        if (event instanceof Error)
+            return event;
+        if (event && typeof event === "object" && "error" in event && event.error instanceof Error) {
+            return event.error;
+        }
+        return new Error("WebSocket transport error");
+    }
+    fail(error) {
+        for (const handler of this.errorHandlers)
+            handler(error);
+    }
+    finish(event) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.pending.length = 0;
+        if (event?.code === 1008 && event.reason === "authentication failed") {
+            this.onAuthenticationRejected?.();
+        }
+        for (const handler of this.closeHandlers)
+            handler();
+    }
+}

package/package.json

@@ -1,45 +1,53 @@
 {
   "name": "cmux",
-  "version": "0.3.6",
-  "description": "Cloud VMs for development - spawn isolated dev environments instantly",
-  "keywords": [
-    "cli",
-    "devbox",
-    "cloud",
-    "vm",
-    "development",
-    "sandbox",
-    "remote",
-    "vscode"
-  ],
-  "homepage": "https://cmux.sh",
+  "version": "0.4.0",
+  "description": "Typed TypeScript client for cmux-tui frontends",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/manaflow-ai/cmux.git",
-    "directory": "packages/cmux-devbox"
+    "directory": "cmux-tui/bindings/typescript"
   },
-  "license": "MIT",
-  "author": "Manaflow",
-  "bin": {
-    "cmux": "bin/cmux"
+  "homepage": "https://github.com/manaflow-ai/cmux/tree/main/cmux-tui/bindings/typescript",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/src/browser.d.ts",
+        "import": "./dist/src/browser.js",
+        "default": "./dist/src/browser.js"
+      },
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./browser": {
+      "types": "./dist/src/browser.d.ts",
+      "import": "./dist/src/browser.js",
+      "default": "./dist/src/browser.js"
+    },
+    "./node": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
   },
+  "sideEffects": false,
   "files": [
-    "bin",
-    "lib",
-    "AGENTS.md",
-    "llms.txt"
+    "dist/src",
+    "README.md"
   ],
   "scripts": {
-    "postinstall": "node lib/postinstall.js"
-  },
-  "optionalDependencies": {
-    "cmux-darwin-arm64": "0.3.6",
-    "cmux-darwin-x64": "0.3.6",
-    "cmux-linux-arm64": "0.3.6",
-    "cmux-linux-x64": "0.3.6",
-    "cmux-win32-x64": "0.3.6"
+    "build": "tsc",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "e2e": "npm run build && node dist/e2e/e2e.js"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.25",
+    "typescript": "5.9.3"
   }
 }

package/AGENTS.md

@@ -1,87 +0,0 @@
-# cmux CLI - Agent Instructions
-
-cmux is a CLI for managing cloud development VMs. Use these commands to help users work with remote development environments.
-
-## Quick Reference
-
-```bash
-# Authentication
-cmux login               # Login (opens browser)
-cmux logout              # Logout
-cmux whoami              # Show current user and team
-
-# VM Lifecycle
-cmux start [path]        # Create VM, optionally sync directory
-cmux ls                  # List all VMs
-cmux status <id>         # Show VM details and URLs
-cmux pause <id>          # Pause VM (preserves state, saves cost)
-cmux resume <id>         # Resume paused VM
-cmux delete <id>         # Delete VM permanently
-
-# Access VM
-cmux code <id>           # Open VS Code in browser
-cmux ssh <id>            # SSH into VM
-cmux vnc <id>            # Open VNC desktop
-cmux pty <id>            # Interactive terminal session
-
-# Work with VM
-cmux exec <id> "cmd"     # Run command in VM
-cmux sync <id> <path>    # Sync local files to VM
-cmux sync <id> <path> --pull  # Pull files from VM
-
-# Browser Automation (control Chrome in VNC)
-cmux computer open <id> <url>           # Navigate to URL
-cmux computer snapshot <id>             # Get interactive elements (@e1, @e2...)
-cmux computer click <id> <selector>     # Click element (@e1 or CSS selector)
-cmux computer type <id> "text"          # Type into focused element
-cmux computer fill <id> <sel> "value"   # Clear and fill input
-cmux computer screenshot <id> [file]    # Take screenshot
-cmux computer press <id> <key>          # Press key (enter, tab, escape)
-```
-
-## VM IDs
-
-VM IDs look like `cmux_abc12345`. Always use the full ID when running commands.
-
-## Common Workflows
-
-### Create and access a VM
-```bash
-cmux start ./my-project    # Creates VM, syncs directory, returns ID
-cmux code cmux_abc123      # Opens VS Code
-```
-
-### Run commands remotely
-```bash
-cmux exec cmux_abc123 "npm install"
-cmux exec cmux_abc123 "npm run dev"
-```
-
-### Sync files
-```bash
-cmux sync cmux_abc123 .              # Push current dir to VM
-cmux sync cmux_abc123 ./dist --pull  # Pull build output from VM
-```
-
-### Browser automation
-```bash
-cmux computer open cmux_abc123 "https://localhost:3000"
-cmux computer snapshot cmux_abc123   # See clickable elements
-cmux computer click cmux_abc123 @e1  # Click first element
-```
-
-### End of session
-```bash
-cmux pause cmux_abc123    # Pause to save costs (can resume later)
-# OR
-cmux delete cmux_abc123   # Delete permanently
-```
-
-## Tips
-
-- Run `cmux login` first if not authenticated
-- Use `cmux whoami` to check current user and team
-- Use `cmux ls` to see all VMs and their states
-- Paused VMs preserve state and can be resumed instantly
-- The `cmux pty` command requires an interactive terminal
-- Browser automation commands work on the Chrome instance in the VNC desktop

package/bin/cmux

@@ -1,97 +0,0 @@
-#!/usr/bin/env node
-
-const { spawn } = require("child_process");
-const path = require("path");
-const fs = require("fs");
-
-const PLATFORMS = {
-  "darwin-arm64": "cmux-darwin-arm64",
-  "darwin-x64": "cmux-darwin-x64",
-  "linux-arm64": "cmux-linux-arm64",
-  "linux-x64": "cmux-linux-x64",
-  "win32-x64": "cmux-win32-x64",
-};
-
-// Map platform to local directory name (for development)
-const LOCAL_DIRS = {
-  "darwin-arm64": "darwin-arm64",
-  "darwin-x64": "darwin-x64",
-  "linux-arm64": "linux-arm64",
-  "linux-x64": "linux-x64",
-  "win32-x64": "win32-x64",
-};
-
-function getBinaryPath() {
-  const platform = `${process.platform}-${process.arch}`;
-  const pkg = PLATFORMS[platform];
-  const localDir = LOCAL_DIRS[platform];
-
-  if (!pkg) {
-    console.error(`cmux: Unsupported platform: ${platform}`);
-    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
-    process.exit(1);
-  }
-
-  const binName = process.platform === "win32" ? "cmux.exe" : "cmux";
-
-  // Try to find the platform-specific package from node_modules
-  try {
-    const pkgPath = require.resolve(`${pkg}/package.json`);
-    const pkgDir = path.dirname(pkgPath);
-    const binPath = path.join(pkgDir, "bin", binName);
-
-    if (fs.existsSync(binPath)) {
-      return binPath;
-    }
-  } catch (e) {
-    // Package not found in node_modules
-  }
-
-  // Try local development path (sibling directory)
-  const localBinPath = path.join(__dirname, "..", "..", localDir, "bin", binName);
-  if (fs.existsSync(localBinPath)) {
-    return localBinPath;
-  }
-
-  console.error(`cmux: Could not find binary for platform: ${platform}`);
-  console.error(`Make sure ${pkg} is installed.`);
-  console.error("");
-  console.error("Try reinstalling with:");
-  console.error("  npm install cmux");
-  process.exit(1);
-}
-
-function main() {
-  const binPath = getBinaryPath();
-  const args = process.argv.slice(2);
-
-  // Use spawn for better signal handling (especially for PTY)
-  const child = spawn(binPath, args, {
-    stdio: "inherit",
-    windowsHide: true,
-  });
-
-  child.on("error", (err) => {
-    console.error(`cmux: Failed to start: ${err.message}`);
-    process.exit(1);
-  });
-
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      // Re-raise the signal
-      process.kill(process.pid, signal);
-    } else {
-      process.exit(code ?? 0);
-    }
-  });
-
-  // Forward signals to child
-  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
-  for (const sig of signals) {
-    process.on(sig, () => {
-      child.kill(sig);
-    });
-  }
-}
-
-main();

package/lib/postinstall.js

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-
-// Post-install message for cmux
-// Only show in interactive terminals to avoid noise in CI
-
-const isCI = process.env.CI === 'true' ||
-             process.env.CONTINUOUS_INTEGRATION === 'true' ||
-             process.env.BUILD_NUMBER !== undefined ||
-             process.env.GITHUB_ACTIONS === 'true';
-
-const isInteractive = process.stdout.isTTY && !isCI;
-
-if (isInteractive) {
-  const message = `
-┌─────────────────────────────────────────────────────────┐
-│                                                         │
-│   ✨ cmux installed successfully!                       │
-│                                                         │
-│   Get started:                                          │
-│     $ cmux login          # Login to your account       │
-│     $ cmux start          # Create a cloud VM           │
-│     $ cmux --help         # See all commands            │
-│                                                         │
-│   Documentation: https://cmux.sh/docs                   │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-`;
-  console.log(message);
-}

package/llms.txt

@@ -1,70 +0,0 @@
-# cmux
-
-> Cloud VMs for development - spawn isolated dev environments instantly
-
-cmux is a CLI tool for managing cloud development VMs. It provides instant access to fully configured development environments with VS Code, VNC desktop, SSH, and browser automation.
-
-## Installation
-
-```bash
-npm install -g cmux
-```
-
-## Commands
-
-### Authentication
-- `cmux login` - Login via browser
-- `cmux logout` - Logout
-- `cmux whoami` - Show current user and team
-
-### VM Management
-- `cmux start [path]` - Create new VM, optionally sync a directory
-- `cmux ls` - List all VMs (aliases: list, ps)
-- `cmux status <id>` - Show VM status and URLs
-- `cmux pause <id>` - Pause VM (preserves state)
-- `cmux resume <id>` - Resume paused VM
-- `cmux delete <id>` - Delete VM permanently
-
-### Accessing VMs
-- `cmux code <id>` - Open VS Code in browser
-- `cmux ssh <id>` - SSH into VM
-- `cmux vnc <id>` - Open VNC desktop in browser
-- `cmux pty <id>` - Interactive terminal session
-
-### Working with VMs
-- `cmux exec <id> "command"` - Execute command in VM
-- `cmux sync <id> <path>` - Sync local directory to VM
-- `cmux sync <id> <path> --pull` - Pull from VM to local
-
-### Browser Automation
-Control Chrome running in the VNC desktop:
-- `cmux computer open <id> <url>` - Navigate to URL
-- `cmux computer snapshot <id>` - Get accessibility tree with element refs (@e1, @e2)
-- `cmux computer click <id> <selector>` - Click element (use @ref or CSS selector)
-- `cmux computer type <id> "text"` - Type into focused element
-- `cmux computer fill <id> <selector> "value"` - Clear and fill input
-- `cmux computer screenshot <id> [file]` - Take screenshot
-- `cmux computer press <id> <key>` - Press key (enter, tab, escape, etc.)
-
-## Examples
-
-Create a VM and run a dev server:
-```bash
-cmux start ./my-app
-cmux exec cmux_abc123 "npm install && npm run dev"
-cmux code cmux_abc123
-```
-
-Automate browser testing:
-```bash
-cmux computer open cmux_abc123 "http://localhost:3000"
-cmux computer snapshot cmux_abc123
-cmux computer click cmux_abc123 @e1
-cmux computer screenshot cmux_abc123 test.png
-```
-
-## Links
-
-- Homepage: https://cmux.sh
-- Documentation: https://cmux.sh/docs
-- GitHub: https://github.com/manaflow-ai/cmux