@volter/supercode-terminal 0.2.30

package/substrate/attach.js

@@ -0,0 +1,147 @@
+import { Buffer } from "node:buffer";
+import { TerminalClient } from "./client.js";
+// Connect the calling terminal directly to a live provider terminal — the raw
+// PTY pipe behind an `attach` / `control` / `chat --attach` door. It reuses
+// the same duplex socket the browser mirror speaks (TerminalClient: an `output`
+// stream in, `input` writes out), so there is no second transport: stdin →
+// input, output → stdout, and a tmux-style prefix key detaches without killing
+// the session (it stays live on the provider, durable on disk, reapable).
+// Ctrl-b, then `d` — the tmux detach chord. A lone prefix is held until the next
+// key so a real Ctrl-b still reaches the inner program (delayed one keystroke);
+// Ctrl-b Ctrl-b sends a literal Ctrl-b. This is the ONE place the chord is
+// decoded, kept pure (no socket/tty) so it is unit-testable.
+export const detachPrefixByte = 0x02; // Ctrl-b
+export const detachKeyByte = 0x64; // d
+export function createDetachFilter(opts) {
+    const prefix = opts.prefix ?? detachPrefixByte;
+    const key = opts.key ?? detachKeyByte;
+    let armed = false;
+    return {
+        feed(chunk) {
+            const bytes = typeof chunk === "string" ? [...Buffer.from(chunk, "utf8")] : [...chunk];
+            const out = [];
+            const flush = () => {
+                if (out.length === 0)
+                    return;
+                opts.onInput(Buffer.from(out).toString("utf8"));
+                out.length = 0;
+            };
+            for (const byte of bytes) {
+                if (armed) {
+                    armed = false;
+                    if (byte === key) {
+                        flush();
+                        opts.onDetach();
+                        return;
+                    }
+                    // Ctrl-b Ctrl-b → a literal Ctrl-b reaches the inner program; any
+                    // other key after the prefix forwards both bytes unchanged.
+                    out.push(prefix);
+                    if (byte !== prefix)
+                        out.push(byte);
+                    continue;
+                }
+                if (byte === prefix) {
+                    armed = true;
+                    continue;
+                }
+                out.push(byte);
+            }
+            flush();
+        }
+    };
+}
+// Raw-pipe the calling terminal to `terminalId` on the provider at `baseUrl`.
+// Resolves when the remote pane exits or the user detaches (Ctrl-b d). Restores
+// the local tty on every exit path and follows live TTY resize events.
+export async function attachTerminal(opts) {
+    const stdin = opts.streams?.stdin ?? process.stdin;
+    const stdout = opts.streams?.stdout ?? process.stdout;
+    const cols = stdout.columns ?? 80;
+    const rows = stdout.rows ?? 24;
+    const client = new TerminalClient({
+        ...(opts.authToken ? { authToken: opts.authToken } : {}),
+        baseUrl: opts.baseUrl,
+        cols,
+        rows,
+        terminalId: opts.terminalId
+    });
+    const socket = client.connect();
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const onStdin = (chunk) => filter.feed(chunk);
+        const onResize = () => {
+            if (socket.readyState !== socket.OPEN)
+                return;
+            client.resize(stdout.columns ?? 80, stdout.rows ?? 24);
+        };
+        // A real Ctrl-C is forwarded to the remote pane as a raw byte (raw mode), so
+        // it never lands here — these fire only on an EXTERNAL kill (or a parent
+        // termination). Without restoring the tty first, the process would die with
+        // raw mode still on, leaving the user's shell with no echo (needs `reset`).
+        const onSignal = () => finish({ reason: "detached" });
+        const cleanup = () => {
+            stdin.off("data", onStdin);
+            stdout.off("resize", onResize);
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+            try {
+                client.close();
+            }
+            catch {
+                /* socket already closing */
+            }
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(result);
+        };
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        const filter = createDetachFilter({
+            onDetach: () => finish({ reason: "detached" }),
+            onInput: (data) => {
+                if (socket.readyState === socket.OPEN)
+                    client.write(data);
+            }
+        });
+        socket.onopen = () => {
+            if (stdin.isTTY)
+                stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on("data", onStdin);
+            stdout.on("resize", onResize);
+        };
+        socket.onmessage = (event) => {
+            // After detach/exit, a still-buffered frame must not write stray bytes to
+            // the now-foreground shell.
+            if (settled)
+                return;
+            const raw = typeof event.data === "string" ? event.data : String(event.data);
+            const message = client.parse(raw);
+            if (message.type === "output") {
+                stdout.write(message.data);
+            }
+            else if (message.type === "exit") {
+                finish({ exitCode: message.exitCode, reason: "exited" });
+            }
+            else if (message.type === "error" || message.type === "input-rejected") {
+                stdout.write(`\r\n[attach] ${message.message}\r\n`);
+            }
+        };
+        socket.onclose = () => finish({ reason: "exited" });
+        socket.onerror = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(new Error(`Could not attach to terminal ${opts.terminalId} at ${opts.baseUrl}.`));
+        };
+    });
+}

package/substrate/client.d.ts

@@ -0,0 +1,62 @@
+export type TerminalUrlResolver = {
+    wsAuthQuery(): Record<string, string>;
+    wsBase(baseUrl: string): string;
+    /**
+     * The socket of one terminal, for a host that addresses each by path (a
+     * Conduit terminal binding's `/sessions/{id}/ws`). Given, the terminal and
+     * its size are not added to the URL: the size goes as a `resize` message
+     * once the socket is open, as it does for any resize.
+     */
+    wsUrl?(baseUrl: string, terminalId: string): string;
+};
+export declare const directTerminalUrlResolver: TerminalUrlResolver;
+export type TerminalHelloMessage = {
+    type: "hello";
+    cols: number;
+    rows: number;
+};
+export type TerminalOutputMessage = {
+    type: "output";
+    data: string;
+};
+export type TerminalExitMessage = {
+    type: "exit";
+    exitCode: number;
+    signal?: number;
+};
+export type TerminalErrorMessage = {
+    type: "error";
+    message: string;
+};
+export type TerminalInputRejectedMessage = {
+    type: "input-rejected";
+    message: string;
+};
+export type TerminalMessage = TerminalHelloMessage | TerminalOutputMessage | TerminalExitMessage | TerminalErrorMessage | TerminalInputRejectedMessage;
+export type TerminalClientOptions = {
+    authToken?: () => string | undefined;
+    baseUrl: string;
+    cols?: number;
+    rows?: number;
+    terminalId: string;
+    urlResolver?: TerminalUrlResolver;
+};
+export declare class TerminalClient {
+    /** The size last asked for: the constructor's, then each resize's. */
+    cols: number | undefined;
+    rows: number | undefined;
+    readonly terminalId: string;
+    private readonly authToken?;
+    private socket?;
+    private readonly baseUrl;
+    private readonly urls;
+    constructor({ authToken, baseUrl, cols, rows, terminalId, urlResolver }: TerminalClientOptions);
+    connect(): WebSocket;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+    parse(raw: string): TerminalMessage;
+    private requireOpenSocket;
+    private url;
+}
+export declare function webSocketBaseUrl(baseUrl: string): string;

package/substrate/client.js

@@ -0,0 +1,138 @@
+export const directTerminalUrlResolver = {
+    wsAuthQuery: () => ({}),
+    wsBase: (baseUrl) => webSocketBaseUrl(baseUrl)
+};
+export class TerminalClient {
+    /** The size last asked for: the constructor's, then each resize's. */
+    cols;
+    rows;
+    terminalId;
+    authToken;
+    socket;
+    baseUrl;
+    urls;
+    constructor({ authToken, baseUrl, cols, rows, terminalId, urlResolver }) {
+        this.authToken = authToken;
+        this.baseUrl = baseUrl;
+        this.cols = cols;
+        this.rows = rows;
+        this.terminalId = terminalId;
+        this.urls = urlResolver ?? directTerminalUrlResolver;
+    }
+    connect() {
+        if (this.socket && this.socket.readyState !== WebSocket.CLOSED && this.socket.readyState !== WebSocket.CLOSING) {
+            return this.socket;
+        }
+        const socket = new WebSocket(this.url());
+        this.socket = socket;
+        // a host addressed by path learns the size as the first resize, after its hello
+        if (this.urls.wsUrl && this.cols !== undefined && this.rows !== undefined) {
+            const onHello = (event) => {
+                try {
+                    if (this.parse(String(event.data)).type !== "hello")
+                        return;
+                }
+                catch {
+                    return;
+                }
+                socket.removeEventListener("message", onHello);
+                // the size as it is now: a view that fitted while the socket opened resized since
+                if (socket.readyState === WebSocket.OPEN)
+                    socket.send(JSON.stringify({ cols: this.cols, rows: this.rows, type: "resize" }));
+            };
+            socket.addEventListener("message", onHello);
+        }
+        return socket;
+    }
+    write(data) {
+        const socket = this.requireOpenSocket();
+        socket.send(JSON.stringify({ data, type: "input" }));
+    }
+    resize(cols, rows) {
+        assertTerminalDimension(cols, "cols");
+        assertTerminalDimension(rows, "rows");
+        this.cols = cols;
+        this.rows = rows;
+        const socket = this.requireOpenSocket();
+        socket.send(JSON.stringify({ cols, rows, type: "resize" }));
+    }
+    close() {
+        this.socket?.close();
+    }
+    parse(raw) {
+        const message = JSON.parse(raw);
+        if (message.type === "hello") {
+            const cols = message.cols;
+            const rows = message.rows;
+            if (cols === undefined || rows === undefined || !Number.isInteger(cols) || !Number.isInteger(rows)) {
+                throw new Error(`Hello message for ${this.terminalId} did not include cols and rows.`);
+            }
+            return { cols, rows, type: "hello" };
+        }
+        if (message.type === "output") {
+            if (typeof message.data !== "string") {
+                throw new Error(`Output message for ${this.terminalId} did not include data.`);
+            }
+            return { data: message.data, type: "output" };
+        }
+        if (message.type === "exit") {
+            const exitCode = message.exitCode;
+            if (exitCode === undefined || !Number.isInteger(exitCode)) {
+                throw new Error(`Exit message for ${this.terminalId} did not include an exit code.`);
+            }
+            return { exitCode, signal: message.signal, type: "exit" };
+        }
+        if (message.type === "error") {
+            return { message: message.message ?? `WebSocket error for ${this.terminalId}.`, type: "error" };
+        }
+        if (message.type === "input-rejected") {
+            return { message: message.message ?? `Input rejected for ${this.terminalId}.`, type: "input-rejected" };
+        }
+        throw new Error(`Unsupported message type: ${String(message.type)}`);
+    }
+    requireOpenSocket() {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            throw new Error(`Terminal socket for ${this.terminalId} is not open.`);
+        }
+        return socket;
+    }
+    url() {
+        if (this.urls.wsUrl) {
+            const addressed = new URL(this.urls.wsUrl(this.baseUrl, this.terminalId));
+            for (const [name, value] of Object.entries(this.urls.wsAuthQuery()))
+                addressed.searchParams.set(name, value);
+            return addressed.href;
+        }
+        const url = new URL(`${this.urls.wsBase(this.baseUrl)}/ws`);
+        url.searchParams.set("terminalId", this.terminalId);
+        // Only send a size when the caller actually specified one (see
+        // TerminalClientOptions.cols/rows) — an omitted cols/rows must reach the
+        // gateway as an ABSENT query param, never "undefined" as a string, so its
+        // own `value === null` fallback to the pane's live size still fires.
+        if (this.cols !== undefined) {
+            url.searchParams.set("cols", String(this.cols));
+        }
+        if (this.rows !== undefined) {
+            url.searchParams.set("rows", String(this.rows));
+        }
+        const token = this.authToken?.();
+        if (token) {
+            url.searchParams.set("token", token);
+        }
+        for (const [name, value] of Object.entries(this.urls.wsAuthQuery())) {
+            url.searchParams.set(name, value);
+        }
+        return url.href;
+    }
+}
+function assertTerminalDimension(value, label) {
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw new Error(`Terminal ${label} must be an integer between 1 and 1000.`);
+    }
+}
+export function webSocketBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    return url.origin;
+}

package/substrate/docker-exec.d.ts

@@ -0,0 +1,41 @@
+import type { TerminalConnector, TerminalUiState } from "@volter/supercode-terminal/ui";
+/** A WebSocket, or a page's own socket onto an exec's stream with that shape. */
+export interface DockerExecSocket extends EventTarget {
+    readonly readyState: number;
+    binaryType: "blob" | "arraybuffer";
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+}
+export interface DockerExecTerminalOptions {
+    /** The daemon's base, versioned or not: `http://agent/v1.51`, a binding's base, this page's origin. */
+    base: string;
+    containerId: string;
+    /** Opens `/exec/{id}/start`; a WebSocket to the same address by default. */
+    socket?: (url: string) => DockerExecSocket;
+    /** Sent with every request: a bearer token for an agent, nothing in a tab. */
+    headers?: Record<string, string>;
+    shell?: readonly string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Bytes of each shell's newest output a view replays when it attaches. */
+    bufferBytes?: number;
+}
+/** One shell's own start, over the controller's defaults. */
+export interface DockerExecShellOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    label?: string;
+}
+export interface DockerExecTerminal {
+    getState(): TerminalUiState;
+    subscribe(listener: () => void): () => void;
+    readonly connector: TerminalConnector;
+    /** Opens a shell and attaches to it; resolves to its id, rejects with the daemon's words. */
+    create(shell?: DockerExecShellOptions): Promise<string>;
+    attach(sessionId: string): void;
+    /** Ends a shell, or dismisses one that exited. */
+    stop(sessionId: string): Promise<void>;
+    /** Ends every shell. */
+    dispose(): void;
+}
+export declare function dockerExecTerminal(options: DockerExecTerminalOptions): DockerExecTerminal;

package/substrate/docker-exec.js

@@ -0,0 +1,101 @@
+export function dockerExecTerminal(options) {
+    const base = options.base.replace(/\/$/u, "");
+    const headers = options.headers ?? {};
+    const limit = options.bufferBytes ?? 256 * 1024;
+    const openSocket = options.socket ?? ((url) => new WebSocket(url.replace(/^http/u, "ws")));
+    let state = { available: true, canOpenLocal: false, error: null, sessions: [], attachment: null };
+    const listeners = new Set();
+    const set = (next) => { state = { ...state, ...next }; for (const listener of listeners)
+        listener(); };
+    const shells = new Map();
+    let count = 0;
+    const resize = (id, cols, rows) => {
+        void fetch(`${base}/exec/${id}/resize?h=${rows}&w=${cols}`, { method: "POST", headers }).catch(() => undefined);
+    };
+    const attach = (sessionId) => set({ attachment: { id: `${sessionId}:${Date.now()}`, baseUrl: base, mode: "control", sessionId } });
+    const connector = (attachment, handlers, size) => {
+        const id = attachment.sessionId ?? attachment.id;
+        const shell = shells.get(id);
+        if (!shell) {
+            handlers.onError("This shell has ended.");
+            return { write() { }, resize() { }, close() { } };
+        }
+        handlers.onOpen();
+        if (shell.output)
+            handlers.onOutput(shell.output);
+        if (shell.exited)
+            handlers.onExit();
+        else
+            resize(id, size.cols, size.rows);
+        shell.views.add(handlers);
+        return {
+            write(data) { if (!shell.exited && shell.socket.readyState === 1)
+                shell.socket.send(data); },
+            resize(cols, rows) { if (!shell.exited)
+                resize(id, cols, rows); },
+            // a view detaching leaves its shell running
+            close() { shell.views.delete(handlers); },
+        };
+    };
+    async function stop(id) {
+        const shell = shells.get(id);
+        shells.delete(id);
+        shell?.socket.close();
+        set({
+            sessions: state.sessions.filter((x) => x.id !== id),
+            attachment: state.attachment?.sessionId === id ? null : state.attachment,
+        });
+    }
+    return {
+        getState: () => state,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        connector,
+        attach,
+        stop,
+        async create(start = {}) {
+            const cwd = start.cwd ?? options.cwd;
+            const env = { ...(options.env ?? {}), ...(start.env ?? {}) };
+            const response = await fetch(`${base}/containers/${options.containerId}/exec`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...headers },
+                body: JSON.stringify({
+                    Cmd: options.shell ?? ["sh"], Tty: true, AttachStdin: true, AttachStdout: true, AttachStderr: true,
+                    ...(cwd ? { WorkingDir: cwd } : {}),
+                    Env: ["TERM=xterm-256color", ...Object.entries(env).map(([key, value]) => `${key}=${value}`)],
+                }),
+            });
+            const created = await response.json().catch(() => ({}));
+            if (!response.ok || !created.Id)
+                throw new Error(created.message ?? `The container refused a shell (${response.status}).`);
+            const id = created.Id;
+            const socket = openSocket(`${base}/exec/${id}/start?h=24&w=80`);
+            socket.binaryType = "arraybuffer";
+            const shell = { socket, output: "", exited: false, views: new Set() };
+            // each shell's own decoder: a character split across frames stays whole
+            const decoder = new TextDecoder();
+            shells.set(id, shell);
+            socket.addEventListener("message", (event) => {
+                const data = event.data;
+                const text = typeof data === "string" ? data : decoder.decode(data, { stream: true });
+                shell.output = (shell.output + text).slice(-limit);
+                for (const view of shell.views)
+                    view.onOutput(text);
+            });
+            socket.addEventListener("error", () => { for (const view of shell.views)
+                view.onError("The shell's connection failed."); });
+            socket.addEventListener("close", () => {
+                if (shells.get(id) !== shell)
+                    return;
+                shell.exited = true;
+                set({ sessions: state.sessions.map((x) => (x.id === id ? { ...x, activeCommand: "exited" } : x)) });
+                for (const view of shell.views)
+                    view.onExit();
+            });
+            set({ sessions: [...state.sessions, { id, label: start.label ?? `Shell ${++count}`, cwd: cwd ?? null, activeCommand: null, owned: true }], error: null });
+            attach(id);
+            return id;
+        },
+        dispose() { for (const id of [...shells.keys()])
+            void stop(id); },
+    };
+}

package/substrate/internal/exec.d.ts

@@ -0,0 +1,15 @@
+export type RunOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    inheritEnv?: boolean;
+    timeoutMs?: number;
+};
+export declare function commandExists(command: string): boolean;
+export declare function requireCommand(command: string, installHint?: string): void;
+export declare function ensureSystemToolsOnPath(): void;
+export declare function run(command: string, args: string[], options?: RunOptions): string;
+export declare function runBuffer(command: string, args: string[], options?: RunOptions): Buffer;
+export declare function runWithInput(command: string, args: string[], input: Buffer, options?: RunOptions): Buffer;
+export declare function runAsync(command: string, args: string[], options?: RunOptions): Promise<string>;
+export declare function runWithInputAsync(command: string, args: string[], input: Buffer | string, options?: RunOptions): Promise<string>;
+export declare function spawnInherited(command: string, args: string[]): void;