@zq-silk/yui 0.2.0 → 0.4.2

package/dist/web/tmuxWebTerminal.js

@@ -0,0 +1,158 @@
+import * as pty from "node-pty";
+import { yuiTmuxServerName } from "../tmux/tmuxManager.js";
+/**
+ * Creates only a tmux client PTY. Closing it detaches the browser while the
+ * native Agent process remains owned by the existing tmux Role window.
+ */
+export class TmuxWebTerminalService {
+    options;
+    #writers = new Set();
+    #spawnPty;
+    constructor(options) {
+        this.options = options;
+        this.#spawnPty = options.spawnPty ?? ((command, args, ptyOptions) => (pty.spawn(command, args, ptyOptions)));
+    }
+    async open(request) {
+        const hostId = request.scope === "task" ? request.taskId : "operator";
+        if (request.scope === "task") {
+            await this.options.prepareTaskRole({
+                taskId: request.taskId,
+                roleName: request.roleName
+            });
+        }
+        else {
+            await this.options.prepareGlobalRole(request.roleName);
+        }
+        const roleHistory = this.options.tmux.inspectRoleHistory?.(hostId, request.roleName);
+        const readOnly = this.#writers.has(hostId)
+            || this.options.tmux.hasWritableClient(hostId);
+        if (!readOnly)
+            this.#writers.add(hostId);
+        let clientSession;
+        let process;
+        try {
+            clientSession = this.options.tmux.createInteractiveClientSession(hostId);
+            process = this.#spawnPty(this.options.tmuxBin, [
+                "-L", yuiTmuxServerName(this.options.yuiHome),
+                "attach-session",
+                ...(readOnly ? ["-r"] : []),
+                "-t",
+                `${clientSession}:${request.roleName}`
+            ], {
+                name: "xterm-256color",
+                cols: request.columns,
+                rows: request.rows,
+                cwd: this.options.yuiHome,
+                env: {
+                    ...(this.options.environment ?? processEnvironment()),
+                    TERM: "xterm-256color"
+                }
+            });
+        }
+        catch (error) {
+            if (!readOnly)
+                this.#writers.delete(hostId);
+            if (clientSession !== undefined) {
+                this.destroyClientSession(clientSession);
+            }
+            throw error;
+        }
+        let closed = false;
+        let clientReleased = false;
+        const releaseClient = () => {
+            if (clientReleased)
+                return;
+            clientReleased = true;
+            if (!readOnly)
+                this.#writers.delete(hostId);
+            this.destroyClientSession(clientSession);
+        };
+        const dataListeners = new Set();
+        const exitListeners = new Set();
+        const bufferedData = [];
+        let completedExit;
+        const dataLifecycle = process.onData((data) => {
+            if (dataListeners.size === 0) {
+                bufferedData.push(data);
+                return;
+            }
+            for (const listener of dataListeners)
+                listener(data);
+        });
+        const exitLifecycle = process.onExit((exit) => {
+            completedExit = exit;
+            releaseClient();
+            for (const listener of exitListeners)
+                listener(exit);
+            exitListeners.clear();
+        });
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            dataLifecycle.dispose();
+            exitLifecycle.dispose();
+            dataListeners.clear();
+            exitListeners.clear();
+            bufferedData.length = 0;
+            releaseClient();
+            try {
+                process.kill();
+            }
+            catch {
+                // The tmux client may already have detached or exited.
+            }
+        };
+        return {
+            readOnly,
+            ...(roleHistory === undefined ? {} : {
+                history: {
+                    limit: roleHistory.actual,
+                    target: roleHistory.configured
+                }
+            }),
+            onData(listener) {
+                if (closed)
+                    return () => { };
+                dataListeners.add(listener);
+                for (const data of bufferedData.splice(0))
+                    listener(data);
+                return () => dataListeners.delete(listener);
+            },
+            onExit(listener) {
+                if (completedExit !== undefined) {
+                    listener(completedExit);
+                    return () => { };
+                }
+                if (closed)
+                    return () => { };
+                exitListeners.add(listener);
+                return () => exitListeners.delete(listener);
+            },
+            write(data) {
+                if (!readOnly)
+                    process.write(data);
+            },
+            resize(columns, rows) {
+                process.resize(columns, rows);
+            },
+            close
+        };
+    }
+    destroyClientSession(clientSession) {
+        try {
+            this.options.tmux.destroyInteractiveClientSession(clientSession);
+        }
+        catch (error) {
+            try {
+                this.options.onError?.(error);
+            }
+            catch {
+                // Cleanup reporting must not escape the PTY lifecycle.
+            }
+        }
+    }
+}
+function processEnvironment() {
+    return { ...process.env };
+}

package/dist/web/webServer.js

@@ -0,0 +1,463 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+import { usageError } from "../errors/cliError.js";
+import { DASHBOARD_HTML, findWebAsset } from "./assets/assetManifest.js";
+import { buildWebDashboardSnapshot, buildWebTaskDetail } from "./webSnapshot.js";
+const MAX_JSON_BODY_BYTES = 16 * 1024;
+const MAX_TERMINAL_MESSAGE_BYTES = 64 * 1024;
+const MAX_TERMINAL_BUFFERED_BYTES = 1024 * 1024;
+export function parseWebCommandOptions(args) {
+    let host = "127.0.0.1";
+    let port = 4173;
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index];
+        const value = args[index + 1];
+        if (option === "--host" && value !== undefined) {
+            host = value;
+            index += 1;
+        }
+        else if (option === "--port" && value !== undefined) {
+            port = Number(value);
+            index += 1;
+        }
+        else {
+            throw webUsageError();
+        }
+    }
+    if (!new Set(["127.0.0.1", "::1", "localhost"]).has(host)) {
+        throw usageError("Web host must be a loopback address (127.0.0.1, ::1, or localhost).", webUsage());
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw usageError("Web port must be an integer between 1 and 65535.", webUsage());
+    }
+    return { host, port };
+}
+export function createYuiWebServer(store, dependencies = {}) {
+    const now = dependencies.now ?? (() => new Date());
+    const token = dependencies.token ?? randomBytes(24).toString("base64url");
+    const webSocketServer = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+        maxPayload: MAX_TERMINAL_MESSAGE_BYTES
+    });
+    const server = createServer((request, response) => {
+        void handleHttpRequest(request, response, store, dependencies, token, now).catch(() => {
+            if (!response.headersSent)
+                setSecurityHeaders(response);
+            if (!response.writableEnded) {
+                sendJson(response, 500, { error: "Unable to process Yui web request." }, false);
+            }
+        });
+    });
+    server.on("upgrade", (request, socket, head) => {
+        void handleTerminalUpgrade(request, socket, head, webSocketServer, dependencies.terminal, token);
+    });
+    server.on("close", () => {
+        for (const socket of webSocketServer.clients)
+            socket.terminate();
+        webSocketServer.close();
+    });
+    return server;
+}
+export async function startYuiWebServer(store, options, dependencies = {}) {
+    const server = createYuiWebServer(store, dependencies);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    return server;
+}
+async function handleHttpRequest(request, response, store, dependencies, token, now) {
+    setSecurityHeaders(response);
+    const method = request.method ?? "GET";
+    if (!isLoopbackHost(headerValue(request, "host"))) {
+        sendJson(response, 403, { error: "Invalid Host." }, method === "HEAD");
+        return;
+    }
+    let pathname;
+    try {
+        pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        sendJson(response, 400, { error: "Invalid URL." }, method === "HEAD");
+        return;
+    }
+    if (method === "GET" || method === "HEAD") {
+        try {
+            const asset = findWebAsset(pathname);
+            if (pathname === "/" || pathname === "/index.html") {
+                sendText(response, 200, "text/html; charset=utf-8", dashboardHtml(token), method === "HEAD");
+            }
+            else if (asset !== null) {
+                sendAsset(response, asset, method === "HEAD");
+            }
+            else if (pathname === "/api/dashboard") {
+                sendJson(response, 200, buildWebDashboardSnapshot(store, now()), method === "HEAD");
+            }
+            else if (pathname.startsWith("/api/tasks/")) {
+                const taskId = decodeURIComponent(pathname.slice("/api/tasks/".length));
+                const detail = taskId.length === 0 || taskId.includes("/")
+                    ? null
+                    : buildWebTaskDetail(store, taskId);
+                sendJson(response, detail === null ? 404 : 200, detail ?? { error: "Task not found." }, method === "HEAD");
+            }
+            else {
+                sendJson(response, 404, { error: "Not found." }, method === "HEAD");
+            }
+        }
+        catch (error) {
+            if (error instanceof URIError) {
+                sendJson(response, 400, { error: "Invalid URL encoding." }, method === "HEAD");
+                return;
+            }
+            sendJson(response, 500, { error: "Unable to read Yui state." }, method === "HEAD");
+        }
+        return;
+    }
+    const answerTarget = parseAnswerPath(pathname);
+    if (method === "POST" && answerTarget !== null && dependencies.answerInput !== undefined) {
+        if (!tokenMatches(headerValue(request, "x-yui-web-token"), token)) {
+            sendJson(response, 403, { error: "Invalid Yui web token." }, false);
+            return;
+        }
+        let answer;
+        try {
+            answer = parseWebInputAnswer(await readJsonBody(request));
+        }
+        catch (error) {
+            sendJson(response, 400, {
+                error: error instanceof Error ? error.message : "Invalid input answer."
+            }, false);
+            return;
+        }
+        try {
+            const answered = await dependencies.answerInput({
+                ...answerTarget,
+                answer
+            });
+            sendJson(response, 200, { request: answered }, false);
+        }
+        catch (error) {
+            sendJson(response, 409, {
+                error: error instanceof Error ? error.message : "Unable to answer input request."
+            }, false);
+        }
+        return;
+    }
+    response.setHeader("allow", "GET, HEAD");
+    sendJson(response, 405, { error: "Method not allowed." }, method === "HEAD");
+}
+async function handleTerminalUpgrade(request, socket, head, webSocketServer, terminalPort, token) {
+    try {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (!isLoopbackHost(headerValue(request, "host"))) {
+            rejectUpgrade(socket, 403, "Forbidden");
+            return;
+        }
+        if (url.pathname !== "/api/terminal" || terminalPort === undefined) {
+            rejectUpgrade(socket, 404, "Not Found");
+            return;
+        }
+        if (!tokenMatches(url.searchParams.get("token") ?? undefined, token)) {
+            rejectUpgrade(socket, 403, "Forbidden");
+            return;
+        }
+        const origin = headerValue(request, "origin");
+        const host = headerValue(request, "host");
+        if (origin === undefined || host === undefined || origin !== `http://${host}`) {
+            rejectUpgrade(socket, 403, "Forbidden");
+            return;
+        }
+        const terminalRequest = parseTerminalRequest(url.searchParams);
+        webSocketServer.handleUpgrade(request, socket, head, (webSocket) => {
+            void connectTerminal(webSocket, terminalPort, terminalRequest);
+        });
+    }
+    catch {
+        rejectUpgrade(socket, 400, "Bad Request");
+    }
+}
+async function connectTerminal(webSocket, terminalPort, request) {
+    let disconnected = false;
+    const markDisconnected = () => {
+        disconnected = true;
+    };
+    webSocket.once("close", markDisconnected);
+    webSocket.once("error", markDisconnected);
+    let connection;
+    try {
+        connection = await terminalPort.open(request);
+    }
+    catch (error) {
+        if (!disconnected) {
+            sendWebSocket(webSocket, {
+                type: "error",
+                message: error instanceof Error ? error.message : "Unable to open terminal."
+            });
+            webSocket.close(1011, "Unable to open terminal");
+        }
+        return;
+    }
+    webSocket.off("close", markDisconnected);
+    webSocket.off("error", markDisconnected);
+    if (disconnected || webSocket.readyState !== WebSocket.OPEN) {
+        connection.close();
+        return;
+    }
+    let closed = false;
+    let stopData = () => { };
+    let stopExit = () => { };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        stopData();
+        stopExit();
+        connection.close();
+    };
+    webSocket.once("close", close);
+    webSocket.once("error", close);
+    stopData = connection.onData((data) => {
+        if (webSocket.bufferedAmount > MAX_TERMINAL_BUFFERED_BYTES) {
+            webSocket.close(1013, "Terminal client is too slow");
+            return;
+        }
+        sendWebSocket(webSocket, { type: "data", data });
+    });
+    if (closed) {
+        stopData();
+        return;
+    }
+    stopExit = connection.onExit((exit) => {
+        sendWebSocket(webSocket, { type: "exit", ...exit });
+        webSocket.close(1000, "Terminal detached");
+        close();
+    });
+    if (closed) {
+        stopExit();
+        return;
+    }
+    webSocket.on("message", (payload, binary) => {
+        if (binary) {
+            webSocket.close(1003, "Invalid terminal message");
+            return;
+        }
+        try {
+            const message = parseTerminalClientMessage(String(payload));
+            if (message.type === "resize") {
+                connection.resize(message.columns, message.rows);
+            }
+            else if (!connection.readOnly) {
+                connection.write(message.data);
+            }
+        }
+        catch {
+            webSocket.close(1003, "Invalid terminal message");
+        }
+    });
+    sendWebSocket(webSocket, {
+        type: "ready",
+        readOnly: connection.readOnly,
+        ...(connection.history === undefined ? {} : { history: connection.history })
+    });
+}
+function parseTerminalRequest(parameters) {
+    const scope = parameters.get("scope");
+    const roleName = safeIdentity(parameters.get("role"), "Role");
+    const columns = boundedInteger(parameters.get("cols"), 20, 400, "Terminal columns");
+    const rows = boundedInteger(parameters.get("rows"), 5, 200, "Terminal rows");
+    if (scope === "global") {
+        if (parameters.has("task"))
+            throw new Error("Global terminal cannot include a Task.");
+        return { scope, roleName, columns, rows };
+    }
+    if (scope === "task") {
+        return {
+            scope,
+            taskId: safeIdentity(parameters.get("task"), "Task"),
+            roleName,
+            columns,
+            rows
+        };
+    }
+    throw new Error("Terminal scope is invalid.");
+}
+function parseTerminalClientMessage(value) {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Terminal message must be an object.");
+    }
+    const message = parsed;
+    if (message.type === "input"
+        && Object.keys(message).length === 2
+        && typeof message.data === "string"
+        && Buffer.byteLength(message.data) <= MAX_TERMINAL_MESSAGE_BYTES) {
+        return { type: "input", data: message.data };
+    }
+    if (message.type === "resize"
+        && Object.keys(message).length === 3
+        && Number.isInteger(message.columns)
+        && Number.isInteger(message.rows)) {
+        return {
+            type: "resize",
+            columns: boundedInteger(String(message.columns), 20, 400, "Terminal columns"),
+            rows: boundedInteger(String(message.rows), 5, 200, "Terminal rows")
+        };
+    }
+    throw new Error("Terminal message is invalid.");
+}
+function parseAnswerPath(pathname) {
+    const match = /^\/api\/tasks\/([^/]+)\/inputs\/([^/]+)\/answer$/u.exec(pathname);
+    if (match === null)
+        return null;
+    try {
+        return {
+            taskId: safeIdentity(decodeURIComponent(match[1]), "Task"),
+            inputId: safeIdentity(decodeURIComponent(match[2]), "Input request")
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parseWebInputAnswer(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Input answer must be an object.");
+    }
+    const answer = value;
+    if (Object.keys(answer).length !== 1) {
+        throw new Error("Exactly one of choiceKey or text is required.");
+    }
+    if (typeof answer.choiceKey === "string" && answer.choiceKey.trim().length > 0) {
+        return { choiceKey: answer.choiceKey.trim() };
+    }
+    if (typeof answer.text === "string" && answer.text.trim().length > 0) {
+        return { text: answer.text.trim() };
+    }
+    throw new Error("Exactly one non-empty choiceKey or text is required.");
+}
+async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_JSON_BODY_BYTES)
+            throw new Error("Request body is too large.");
+        chunks.push(buffer);
+    }
+    if (size === 0)
+        throw new Error("Request body is required.");
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new Error("Request body must be valid JSON.");
+    }
+}
+function setSecurityHeaders(response) {
+    response.setHeader("cache-control", "no-store");
+    response.setHeader("content-security-policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'");
+    response.setHeader("referrer-policy", "no-referrer");
+    response.setHeader("x-content-type-options", "nosniff");
+    response.setHeader("x-frame-options", "DENY");
+}
+function sendJson(response, status, value, head) {
+    sendText(response, status, "application/json; charset=utf-8", JSON.stringify(value), head);
+}
+function sendText(response, status, contentType, body, head) {
+    response.statusCode = status;
+    response.setHeader("content-type", contentType);
+    response.setHeader("content-length", Buffer.byteLength(body));
+    response.end(head ? undefined : body);
+}
+function sendAsset(response, asset, head) {
+    const payload = asset.encoding === "base64"
+        ? Buffer.from(asset.body, "base64")
+        : Buffer.from(asset.body, "utf-8");
+    if (asset.contentType.startsWith("font/") || asset.contentType.startsWith("image/")) {
+        response.setHeader("cache-control", "public, max-age=31536000, immutable");
+    }
+    response.statusCode = 200;
+    response.setHeader("content-type", asset.contentType);
+    response.setHeader("content-length", payload.length);
+    response.end(head ? undefined : payload);
+}
+function sendWebSocket(webSocket, value) {
+    if (webSocket.readyState === WebSocket.OPEN) {
+        webSocket.send(JSON.stringify(value));
+    }
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    socket.end(`HTTP/1.1 ${status} ${message}\r\n`
+        + "Connection: close\r\n"
+        + "Content-Length: 0\r\n\r\n");
+}
+function dashboardHtml(token) {
+    return DASHBOARD_HTML.replace('content="__YUI_WEB_TOKEN__"', `content="${escapeHtmlAttribute(token)}"`);
+}
+function tokenMatches(candidate, expected) {
+    if (candidate === undefined)
+        return false;
+    const left = Buffer.from(candidate);
+    const right = Buffer.from(expected);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function headerValue(request, name) {
+    const value = request.headers[name];
+    return Array.isArray(value) ? value[0] : value;
+}
+function isLoopbackHost(value) {
+    if (value === undefined)
+        return false;
+    let url;
+    try {
+        url = new URL(`http://${value}`);
+    }
+    catch {
+        return false;
+    }
+    if (url.username.length > 0
+        || url.password.length > 0
+        || url.pathname !== "/"
+        || url.search.length > 0
+        || url.hash.length > 0) {
+        return false;
+    }
+    const hostname = url.hostname.toLowerCase();
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+function safeIdentity(value, label) {
+    if (value === null || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function boundedInteger(value, minimum, maximum, label) {
+    if (value === null || !/^[0-9]+$/u.test(value))
+        throw new Error(`${label} is invalid.`);
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < minimum || number > maximum) {
+        throw new Error(`${label} must be between ${minimum} and ${maximum}.`);
+    }
+    return number;
+}
+function escapeHtmlAttribute(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function webUsageError() {
+    return usageError("Web usage: yui web [--host <loopback>] [--port <port>].", webUsage());
+}
+function webUsage() {
+    return "Usage: yui web [--host <127.0.0.1|::1|localhost>] [--port <1-65535>]";
+}