cmux 0.1.0 → 0.1.2

package/README.md

@@ -1,16 +1,32 @@
-# cmux
+# cmux TypeScript Client
 
-A multiplexer tool.
+Node.js client for the cmux-mux Unix-socket JSON-lines protocol.
 
-## Installation
+## Build
 
 ```bash
-npm install cmux
+npm i cmux
+npm install
+npm run build
 ```
 
+The package has no runtime dependencies. Node 20 or newer is required.
+
 ## Usage
 
-```javascript
-const cmux = require('cmux');
-console.log(cmux.hello());
-```
+```ts
+import { CmuxClient } from "cmux";
+
+const client = new CmuxClient({ socketPath: process.env.CMUX_MUX_SOCKET });
+const info = await client.identify();
+const created = await client.newWorkspace({ name: "sdk-demo", cols: 80, rows: 24 });
+await client.send(created.surface, { text: "echo hello\r" });
+console.log((await client.readScreen(created.surface)).text);
+await client.close();
+```
+
+## E2E
+
+```bash
+CMUX_MUX_SOCKET=/path/to/session.sock npm run e2e
+```

package/dist/e2e/e2e.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/e2e/e2e.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("../src/index.js");
+async function main() {
+    const socketPath = process.env.CMUX_MUX_SOCKET;
+    if (!socketPath)
+        throw new Error("CMUX_MUX_SOCKET is required");
+    const marker = `CMUX_TS_E2E_${process.pid}_${Date.now()}`;
+    const later = `${marker}_ATTACH`;
+    const client = new index_js_1.CmuxClient({ socketPath, timeoutMs: 5000 });
+    try {
+        const identify = await client.identify();
+        assert(identify.app === "cmux-mux", `unexpected app ${identify.app}`);
+        assert(identify.protocol >= 5 && identify.protocol <= 6, `unsupported protocol ${identify.protocol}`);
+        const created = await client.newWorkspace({ name: marker, cols: 80, rows: 24 });
+        await client.send(created.surface, { text: `printf '${marker}\\n'\r` });
+        await waitForMarker(client, created.surface, marker);
+        const screen = await client.readScreen(created.surface);
+        assert(screen.text.includes(marker), "marker missing from read-screen");
+        const tree = await client.listWorkspaces();
+        const workspaceId = findWorkspaceForSurface(tree, created.surface);
+        assert(workspaceId !== undefined, "new workspace not found");
+        await client.renameSurface(created.surface, `${marker}-renamed`);
+        const events = await client.subscribe();
+        await client.resizeSurface(created.surface, 100, 31);
+        const resized = await nextSurfaceResized(events, created.surface, 1000);
+        assert(resized.cols === 100 && resized.rows === 31, `bad resize event ${JSON.stringify(resized)}`);
+        await client.resizeSurface(created.surface, 100, 31);
+        const duplicate = await nextSurfaceResized(events, created.surface, 500).catch((err) => {
+            if (err instanceof index_js_1.CmuxTimeoutError)
+                return null;
+            throw err;
+        });
+        assert(duplicate === null, "same-size resize emitted surface-resized");
+        events.close();
+        const attach = await client.attachSurface(created.surface);
+        const first = await attach.next(1000);
+        assert(first.event === "vt-state", `first attach event was ${first.event}`);
+        await client.send(created.surface, { text: `printf '${later}\\n'\r` });
+        const output = await nextAttachOutput(attach, 3000);
+        assert(output.event === "output" || output.event === "resized", "attach did not produce output/resized after vt-state");
+        attach.close();
+        await client.closeWorkspace(workspaceId);
+        const afterClose = await client.listWorkspaces();
+        assert(findWorkspaceForSurface(afterClose, created.surface) === undefined, "closed workspace still present");
+        try {
+            await client.readScreen(created.surface);
+            throw new Error("read-screen on closed surface unexpectedly succeeded");
+        }
+        catch (err) {
+            assert(err instanceof index_js_1.CmuxCommandError, `closed surface error was not command error: ${err}`);
+            assert(String(err.message).length > 0, "command error did not preserve server message");
+        }
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+async function waitForMarker(client, surface, marker) {
+    const deadline = Date.now() + 5000;
+    let last = "";
+    while (Date.now() < deadline) {
+        last = (await client.readScreen(surface)).text;
+        if (last.includes(marker))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error(`marker not found; last screen: ${JSON.stringify(last)}`);
+}
+async function nextSurfaceResized(events, surface, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new index_js_1.CmuxTimeoutError("surface-resized not observed");
+        const event = await events.next(remaining);
+        if (event.event === "surface-resized" && event.surface === surface)
+            return event;
+    }
+}
+async function nextAttachOutput(attach, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new index_js_1.CmuxTimeoutError("attach output not observed");
+        const event = await attach.next(remaining);
+        if (event.event === "output" || event.event === "resized")
+            return event;
+    }
+}
+function findWorkspaceForSurface(tree, surface) {
+    for (const workspace of tree.workspaces) {
+        for (const screen of workspace.screens) {
+            for (const pane of screen.panes) {
+                if ("tabs" in pane && pane.tabs?.some((tab) => tab.surface === surface))
+                    return workspace.id;
+            }
+        }
+    }
+    return undefined;
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/src/client.d.ts

@@ -0,0 +1,70 @@
+import { AttachEvent, ClientOptions, EmptyResult, IdentifyResult, JsonObject, NewBrowserTabOptions, NewScreenOptions, NewTabOptions, NewWorkspaceOptions, ReadScreenResult, SelectOptions, SelectTabOptions, SendOptions, SplitOptions, SubscribeEvent, SurfaceResult, Tree, VtStateResult } from "./types.js";
+type ResponseEnvelope = {
+    id?: unknown;
+    ok: true;
+    data: unknown;
+} | {
+    id?: unknown;
+    ok: false;
+    error: string;
+};
+type EventObject = {
+    event: string;
+    [key: string]: unknown;
+};
+export declare function defaultSocketPath(session?: string): string;
+export declare class CmuxStream<T extends EventObject> implements AsyncIterable<T> {
+    private readonly conn;
+    private readonly timeoutMs;
+    private readonly buffered;
+    private closed;
+    private constructor();
+    static open<T extends EventObject>(socketPath: string, timeoutMs: number, request: JsonObject): Promise<CmuxStream<T>>;
+    next(timeoutMs?: number): Promise<T>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+export declare class CmuxClient {
+    readonly socketPath: string;
+    readonly timeoutMs: number;
+    readonly allowProtocolV6Attach: boolean;
+    private connPromise;
+    private nextRequestId;
+    private protocol;
+    constructor(options?: ClientOptions);
+    close(): Promise<void>;
+    sendRaw(obj: JsonObject): Promise<ResponseEnvelope>;
+    request(cmd: string, params?: JsonObject): Promise<unknown>;
+    identify(): Promise<IdentifyResult>;
+    listWorkspaces(): Promise<Tree>;
+    send(surface: number, options?: SendOptions): Promise<EmptyResult>;
+    readScreen(surface: number): Promise<ReadScreenResult>;
+    vtState(surface: number): Promise<VtStateResult>;
+    newTab(options?: NewTabOptions): Promise<SurfaceResult>;
+    newBrowserTab(url: string, options?: NewBrowserTabOptions): Promise<SurfaceResult>;
+    newWorkspace(options?: NewWorkspaceOptions): Promise<SurfaceResult>;
+    newScreen(options?: NewScreenOptions): Promise<SurfaceResult>;
+    split(pane: number, dir: "right" | "down", options?: SplitOptions): Promise<SurfaceResult>;
+    setRatio(pane: number, dir: "right" | "down", ratio: number): Promise<EmptyResult>;
+    setDefaultColors(fg?: string, bg?: string): Promise<EmptyResult>;
+    closeSurface(surface: number): Promise<EmptyResult>;
+    closePane(pane: number): Promise<EmptyResult>;
+    closeScreen(screen: number): Promise<EmptyResult>;
+    closeWorkspace(workspace: number): Promise<EmptyResult>;
+    renamePane(pane: number, name: string): Promise<EmptyResult>;
+    renameSurface(surface: number, name: string): Promise<EmptyResult>;
+    renameScreen(screen: number, name: string): Promise<EmptyResult>;
+    renameWorkspace(workspace: number, name: string): Promise<EmptyResult>;
+    resizeSurface(surface: number, cols: number, rows: number): Promise<EmptyResult>;
+    focusPane(pane: number): Promise<EmptyResult>;
+    selectTab(options?: SelectTabOptions): Promise<EmptyResult>;
+    selectScreen(options?: SelectOptions): Promise<EmptyResult>;
+    selectWorkspace(options?: SelectOptions): Promise<EmptyResult>;
+    moveTab(surface: number, pane: number, index: number): Promise<EmptyResult>;
+    moveWorkspace(workspace: number, index: number): Promise<EmptyResult>;
+    scrollSurface(surface: number, delta: number): Promise<EmptyResult>;
+    subscribe(): Promise<CmuxStream<SubscribeEvent>>;
+    attachSurface(surface: number): Promise<CmuxStream<AttachEvent>>;
+    private nextId;
+}
+export {};

package/dist/src/client.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CmuxClient = exports.CmuxStream = void 0;
+exports.defaultSocketPath = defaultSocketPath;
+const node_buffer_1 = require("node:buffer");
+const net = require("node:net");
+const os = require("node:os");
+const path = require("node:path");
+const errors_js_1 = require("./errors.js");
+function defaultSocketPath(session = "main") {
+    const base = process.env.TMPDIR || os.tmpdir();
+    return path.join(base, `cmux-mux-${process.getuid?.() ?? 0}`, `${session}.sock`);
+}
+class JsonLineConnection {
+    socket;
+    buffer = "";
+    lines = [];
+    waiters = [];
+    closedError = null;
+    constructor(socket) {
+        this.socket = socket;
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => this.onData(chunk));
+        socket.on("error", (err) => this.closeWith(new errors_js_1.CmuxConnectionError(`socket error: ${err.message}`)));
+        socket.on("close", () => this.closeWith(new errors_js_1.CmuxConnectionError("session socket closed")));
+    }
+    static connect(socketPath) {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection({ path: socketPath });
+            socket.once("connect", () => resolve(new JsonLineConnection(socket)));
+            socket.once("error", (err) => reject(new errors_js_1.CmuxConnectionError(`cannot connect to session socket ${socketPath}: ${err.message}`)));
+        });
+    }
+    send(value) {
+        const line = `${JSON.stringify(value)}\n`;
+        return new Promise((resolve, reject) => {
+            this.socket.write(line, "utf8", (err) => {
+                if (err)
+                    reject(new errors_js_1.CmuxConnectionError(`socket write failed: ${err.message}`));
+                else
+                    resolve();
+            });
+        });
+    }
+    async recv(timeoutMs) {
+        const pending = this.nextLine();
+        const line = await withTimeout(pending.promise, timeoutMs, "session did not respond", pending.cancel);
+        try {
+            const value = JSON.parse(line);
+            if (!value || typeof value !== "object" || Array.isArray(value)) {
+                throw new errors_js_1.CmuxProtocolError("server sent non-object JSON line");
+            }
+            return value;
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.CmuxProtocolError)
+                throw err;
+            throw new errors_js_1.CmuxProtocolError(`bad JSON from server: ${err.message}`);
+        }
+    }
+    close() {
+        this.socket.destroy();
+    }
+    nextLine() {
+        if (this.lines.length > 0) {
+            return { promise: Promise.resolve(this.lines.shift()), cancel: () => undefined };
+        }
+        if (this.closedError) {
+            return { promise: Promise.reject(this.closedError), cancel: () => undefined };
+        }
+        const waiter = {
+            active: true,
+            resolve: (_line) => { },
+            reject: (_error) => { },
+        };
+        const promise = new Promise((resolve, reject) => {
+            waiter.resolve = resolve;
+            waiter.reject = reject;
+        });
+        this.waiters.push(waiter);
+        return {
+            promise,
+            cancel: () => {
+                waiter.active = false;
+            },
+        };
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        for (;;) {
+            const index = this.buffer.indexOf("\n");
+            if (index < 0)
+                break;
+            const line = this.buffer.slice(0, index);
+            this.buffer = this.buffer.slice(index + 1);
+            if (line.trim() === "")
+                continue;
+            let delivered = false;
+            while (this.waiters.length > 0) {
+                const waiter = this.waiters.shift();
+                if (!waiter.active)
+                    continue;
+                waiter.resolve(line);
+                delivered = true;
+                break;
+            }
+            if (!delivered)
+                this.lines.push(line);
+        }
+    }
+    closeWith(error) {
+        if (this.closedError)
+            return;
+        this.closedError = error;
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            if (waiter.active)
+                waiter.reject(error);
+        }
+    }
+}
+class CmuxStream {
+    conn;
+    timeoutMs;
+    buffered = [];
+    closed = false;
+    constructor(conn, timeoutMs, buffered) {
+        this.conn = conn;
+        this.timeoutMs = timeoutMs;
+        this.buffered = buffered;
+    }
+    static async open(socketPath, timeoutMs, request) {
+        const conn = await JsonLineConnection.connect(socketPath);
+        await conn.send(request);
+        const requestId = request.id;
+        const buffered = [];
+        for (;;) {
+            const value = await conn.recv(timeoutMs);
+            if (typeof value.event === "string") {
+                buffered.push(value);
+                continue;
+            }
+            if (value.id !== requestId)
+                continue;
+            const response = value;
+            if (response.ok === true)
+                return new CmuxStream(conn, timeoutMs, buffered);
+            throw new errors_js_1.CmuxCommandError(response.error || "unknown error", response.id, response);
+        }
+    }
+    async next(timeoutMs = this.timeoutMs) {
+        if (this.closed)
+            throw new errors_js_1.CmuxConnectionError("stream is closed");
+        if (this.buffered.length > 0)
+            return this.buffered.shift();
+        for (;;) {
+            const value = await this.conn.recv(timeoutMs);
+            if (typeof value.event !== "string")
+                continue;
+            const event = value;
+            if (event.event === "detached")
+                this.close();
+            return event;
+        }
+    }
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            this.conn.close();
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        while (!this.closed) {
+            yield await this.next();
+        }
+    }
+}
+exports.CmuxStream = CmuxStream;
+class CmuxClient {
+    socketPath;
+    timeoutMs;
+    allowProtocolV6Attach;
+    connPromise;
+    nextRequestId = 1;
+    protocol = null;
+    constructor(options = {}) {
+        this.socketPath = options.socketPath ?? defaultSocketPath(options.session ?? "main");
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.allowProtocolV6Attach = options.allowProtocolV6Attach ?? true;
+        this.connPromise = JsonLineConnection.connect(this.socketPath);
+    }
+    async close() {
+        const conn = await this.connPromise;
+        conn.close();
+    }
+    async sendRaw(obj) {
+        const payload = { ...obj };
+        if (!("id" in payload))
+            payload.id = this.nextId();
+        const requestId = payload.id;
+        const conn = await this.connPromise;
+        await conn.send(payload);
+        for (;;) {
+            const response = await conn.recv(this.timeoutMs);
+            if (typeof response.event === "string")
+                continue;
+            if (response.id !== requestId && response.id !== undefined)
+                continue;
+            return response;
+        }
+    }
+    async request(cmd, params = {}) {
+        const response = await this.sendRaw({ id: this.nextId(), cmd, ...dropUndefined(params) });
+        if (response.ok === true)
+            return response.data;
+        throw new errors_js_1.CmuxCommandError(response.error || "unknown error", response.id, response);
+    }
+    async identify() {
+        const result = await this.request("identify");
+        this.protocol = result.protocol;
+        return result;
+    }
+    async listWorkspaces() { return this.request("list-workspaces"); }
+    async send(surface, options = {}) {
+        const bytes = options.bytes instanceof Uint8Array ? node_buffer_1.Buffer.from(options.bytes).toString("base64") : options.bytes;
+        await this.request("send", dropUndefined({ surface, text: options.text, bytes }));
+        return {};
+    }
+    async readScreen(surface) { return this.request("read-screen", { surface }); }
+    async vtState(surface) { return this.request("vt-state", { surface }); }
+    async newTab(options = {}) { return this.request("new-tab", options); }
+    async newBrowserTab(url, options = {}) { return this.request("new-browser-tab", dropUndefined({ url, ...options })); }
+    async newWorkspace(options = {}) { return this.request("new-workspace", options); }
+    async newScreen(options = {}) { return this.request("new-screen", options); }
+    async split(pane, dir, options = {}) { return this.request("split", dropUndefined({ pane, dir, ...options })); }
+    async setRatio(pane, dir, ratio) { await this.request("set-ratio", { pane, dir, ratio }); return {}; }
+    async setDefaultColors(fg, bg) { await this.request("set-default-colors", dropUndefined({ fg, bg })); return {}; }
+    async closeSurface(surface) { await this.request("close-surface", { surface }); return {}; }
+    async closePane(pane) { await this.request("close-pane", { pane }); return {}; }
+    async closeScreen(screen) { await this.request("close-screen", { screen }); return {}; }
+    async closeWorkspace(workspace) { await this.request("close-workspace", { workspace }); return {}; }
+    async renamePane(pane, name) { await this.request("rename-pane", { pane, name }); return {}; }
+    async renameSurface(surface, name) { await this.request("rename-surface", { surface, name }); return {}; }
+    async renameScreen(screen, name) { await this.request("rename-screen", { screen, name }); return {}; }
+    async renameWorkspace(workspace, name) { await this.request("rename-workspace", { workspace, name }); return {}; }
+    async resizeSurface(surface, cols, rows) { await this.request("resize-surface", { surface, cols, rows }); return {}; }
+    async focusPane(pane) { await this.request("focus-pane", { pane }); return {}; }
+    async selectTab(options = {}) { await this.request("select-tab", options); return {}; }
+    async selectScreen(options = {}) { await this.request("select-screen", options); return {}; }
+    async selectWorkspace(options = {}) { await this.request("select-workspace", options); return {}; }
+    async moveTab(surface, pane, index) { await this.request("move-tab", { surface, pane, index }); return {}; }
+    async moveWorkspace(workspace, index) { await this.request("move-workspace", { workspace, index }); return {}; }
+    async scrollSurface(surface, delta) { await this.request("scroll-surface", { surface, delta }); return {}; }
+    async subscribe() {
+        return CmuxStream.open(this.socketPath, this.timeoutMs, { id: this.nextId(), cmd: "subscribe" });
+    }
+    async attachSurface(surface) {
+        const protocol = this.protocol ?? (await this.identify()).protocol;
+        if (protocol > 6 || (protocol > 5 && !this.allowProtocolV6Attach)) {
+            throw new errors_js_1.CmuxProtocolError(`unsupported attach protocol ${protocol}`);
+        }
+        return CmuxStream.open(this.socketPath, this.timeoutMs, { id: this.nextId(), cmd: "attach-surface", surface });
+    }
+    nextId() {
+        return this.nextRequestId++;
+    }
+}
+exports.CmuxClient = CmuxClient;
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function withTimeout(promise, timeoutMs, message, onTimeout) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onTimeout?.();
+            reject(new errors_js_1.CmuxTimeoutError(message));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class CmuxError extends Error {
+    constructor(message: string);
+}
+export declare class CmuxCommandError extends CmuxError {
+    readonly commandId: unknown;
+    readonly response: unknown;
+    constructor(message: string, commandId?: unknown, response?: unknown);
+}
+export declare class CmuxConnectionError extends CmuxError {
+}
+export declare class CmuxProtocolError extends CmuxError {
+}
+export declare class CmuxTimeoutError extends CmuxError {
+}

package/dist/src/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CmuxTimeoutError = exports.CmuxProtocolError = exports.CmuxConnectionError = exports.CmuxCommandError = exports.CmuxError = void 0;
+class CmuxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.CmuxError = CmuxError;
+class CmuxCommandError extends CmuxError {
+    commandId;
+    response;
+    constructor(message, commandId, response) {
+        super(message);
+        this.commandId = commandId;
+        this.response = response;
+    }
+}
+exports.CmuxCommandError = CmuxCommandError;
+class CmuxConnectionError extends CmuxError {
+}
+exports.CmuxConnectionError = CmuxConnectionError;
+class CmuxProtocolError extends CmuxError {
+}
+exports.CmuxProtocolError = CmuxProtocolError;
+class CmuxTimeoutError extends CmuxError {
+}
+exports.CmuxTimeoutError = CmuxTimeoutError;

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./types.js"), exports);