@hellix-ai/cubes 0.1.5 → 0.2.1

package/dist/tui/model.js

@@ -0,0 +1,117 @@
+// What the split view's list shows: the sessions as a tree (a spawned session under the session that
+// spawned it), inside the same sections `cubes ls` and the web use, narrowed by the filters - all pure,
+// so the whole of it is testable without a terminal.
+import { LIVE, sectionize } from "../sessions.js";
+/** One status vocabulary for the list, the header and the tab: the server's lifecycle + activity. */
+export function statusOf(r) {
+    switch (r.status) {
+        case "running":
+            if (r.activity_status === "working")
+                return { glyph: "●", color: 75, label: "working", attention: false };
+            if (r.activity_status === "waiting")
+                return { glyph: "●", color: 214, label: "needs you", attention: true };
+            return { glyph: "●", color: 78, label: "idle", attention: false };
+        case "starting": return { glyph: "◌", color: 80, label: "starting", attention: false };
+        case "stranded": return { glyph: "○", color: 203, label: "stranded", attention: false };
+        case "cancelled": return { glyph: "○", color: 242, label: "ended", attention: false };
+        default: return { glyph: "○", color: 242, label: r.status, attention: false };
+    }
+}
+export function matches(r, f) {
+    if (f.live && !LIVE.has(r.status))
+        return false;
+    if (f.mine && r.created_by_me !== true)
+        return false;
+    const q = f.text.trim().toLowerCase();
+    if (q && !(r.title ?? "").toLowerCase().includes(q) && !r.id.toLowerCase().startsWith(q)
+        && !(r.group_name ?? "").toLowerCase().includes(q))
+        return false;
+    return true;
+}
+const startOf = (r) => r.started_at ?? r.ended_at ?? r.created_at ?? "";
+const order = (a, b) => {
+    const la = LIVE.has(a.row.status);
+    const lb = LIVE.has(b.row.status);
+    if (la !== lb)
+        return la ? -1 : 1;
+    return startOf(b.row).localeCompare(startOf(a.row));
+};
+/**
+ * Build the visible list.
+ *
+ * ⚠ A SPAWNED SESSION LIVES UNDER ITS PARENT, NOT IN ITS OWN GROUP. The tree is what says who started
+ * what; a child filed into a different section would lose its parent and read as a stray root. A
+ * child whose parent is not in the page (paged out, deleted) is shown as a root rather than hidden.
+ *
+ * ⚠ A FILTER KEEPS THE PATH TO A MATCH. A live child under an exited parent is still reachable with
+ * `live` on - the parent stays as the way to it, and it is drawn expanded so the match is visible.
+ *
+ * `expandedOverride` is what the person toggled; without one, a parent starts expanded when anything
+ * under it is live (the work in progress is the thing to see) and collapsed otherwise.
+ */
+export function buildItems(rows, f, expandedOverride) {
+    const byId = new Map(rows.map((r) => [r.id, { row: r, kids: [] }]));
+    const roots = [];
+    for (const n of byId.values()) {
+        const parent = n.row.parent_session_id ? byId.get(n.row.parent_session_id) : undefined;
+        if (parent && parent !== n)
+            parent.kids.push(n);
+        else
+            roots.push(n);
+    }
+    const keep = new Map(); // node matches, or something under it does
+    const anyLive = new Map();
+    const visit = (n) => {
+        n.kids.sort(order);
+        let k = matches(n.row, f);
+        let live = LIVE.has(n.row.status);
+        for (const c of n.kids) {
+            visit(c);
+            if (keep.get(c.row.id))
+                k = true;
+            if (anyLive.get(c.row.id))
+                live = true;
+        }
+        keep.set(n.row.id, k);
+        anyLive.set(n.row.id, live);
+    };
+    roots.forEach(visit);
+    const filtering = f.live || f.mine || f.text.trim() !== "";
+    const visibleRoots = roots.filter((n) => keep.get(n.row.id)).map((n) => n.row);
+    const items = [];
+    const sections = sectionize(visibleRoots);
+    const bare = sections.length === 1 && sections[0].title === "Ungrouped";
+    for (const sec of sections) {
+        const nodes = sec.rows.map((r) => byId.get(r.id));
+        if (!bare)
+            items.push({ kind: "section", title: sec.title, count: countVisible(nodes, keep) });
+        const walk = (n, depth, lasts) => {
+            const kids = n.kids.filter((c) => keep.get(c.row.id));
+            const kidMatch = filtering && kids.length > 0;
+            const expanded = expandedOverride.get(n.row.id) ?? (kidMatch || n.kids.some((c) => anyLive.get(c.row.id) === true));
+            items.push({ kind: "session", row: n.row, depth, lasts, children: kids.length, expanded: expanded && kids.length > 0 });
+            if (expanded)
+                kids.forEach((c, i) => walk(c, depth + 1, [...lasts, i === kids.length - 1]));
+        };
+        nodes.forEach((n) => walk(n, 0, []));
+    }
+    return items;
+}
+function countVisible(nodes, keep) {
+    let c = 0;
+    const go = (n) => { if (keep.get(n.row.id)) {
+        c++;
+        n.kids.forEach(go);
+    } };
+    nodes.forEach(go);
+    return c;
+}
+/** The tree guide in front of a child: `│ ` / blank per ancestor level, then `├─`/`└─`. */
+export function treePrefix(item) {
+    if (item.depth === 0)
+        return "";
+    let s = "";
+    for (let i = 0; i < item.lasts.length - 1; i++)
+        s += item.lasts[i] ? "  " : "│ ";
+    return s + (item.lasts[item.lasts.length - 1] ? "└─" : "├─");
+}

package/dist/tui/paneApp.js

@@ -0,0 +1,162 @@
+// The right pane of the split view: the session itself, under a header (tmux's pane border) that says
+// which one it is - name, group, runner, state - and stays current while you work in it.
+//
+// The list replaces this process (`respawn-pane -k`) to open another session, so it only ever holds
+// one. When an attach ends it SAYS so and waits: there is no automatic reconnect, by decision ("never
+// keep retrying to reattach a session") - `r` reconnects when the person chooses to.
+import { makeApi } from "../api.js";
+import { attach } from "../attach.js";
+import { currentSession } from "../auth.js";
+import { clipboardWriter, readClipboardImage, writeClipboard } from "../clipboard.js";
+import { CubeSpinner, cubeSize } from "../cube.js";
+import { ensureRunning } from "../resume.js";
+import { statusOf } from "./model.js";
+import { ESC, fit, parseKeys, printable, strWidth } from "./term.js";
+import { fmtText, getSessionOption, setPaneOption, setSessionOption, tmux } from "./tmux.js";
+const out = process.stdout;
+const focusList = () => {
+    const left = getSessionOption("@cubes_left");
+    if (left)
+        tmux(["select-pane", "-t", left]);
+};
+/** The header: `● Title · Group · runner · state`, as a tmux format (styles via #[...]). */
+export function headerFor(r, override) {
+    const s = override ?? statusOf({ status: r.status ?? "running", activity_status: r.activity_status ?? null });
+    const parts = [
+        `#[fg=colour${s.color}]${s.glyph}#[default] #[bold]${fmtText(printable(r.title || r.id.slice(0, 8)))}#[nobold]`,
+        fmtText(printable(r.group_name || r.package_name || "no group")),
+        fmtText(printable(r.runner_name || "-")),
+        `#[fg=colour${s.color}]${s.label}#[default]`,
+    ];
+    return parts.join(" #[fg=colour240]·#[default] ");
+}
+function setHeader(r, override) {
+    setPaneOption("@cubes_header", headerFor(r, override));
+    const s = override ?? statusOf({ status: r.status ?? "running", activity_status: r.activity_status ?? null });
+    setSessionOption("@cubes_tab", `${s.glyph} ${printable(r.title || "Cubes session")}`);
+}
+/** Read keys until one is accepted. Raw mode on for as long as we wait. */
+function waitKey(accept) {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        const onData = (b) => {
+            for (const k of parseKeys(b.toString("utf8"))) {
+                if (!accept(k))
+                    continue;
+                process.stdin.off("data", onData);
+                process.stdin.pause();
+                resolve(k);
+                return;
+            }
+        };
+        process.stdin.on("data", onData);
+        process.stdin.resume();
+    });
+}
+/** A few centred lines, nothing else on screen. */
+function message(lines) {
+    const w = out.columns ?? 80;
+    const h = out.rows ?? 24;
+    const top = Math.max(0, Math.floor((h - lines.length) / 2));
+    let s = ESC.hideCursor + ESC.home + ESC.clear;
+    lines.forEach((l, i) => {
+        const t = fit(l.text, Math.min(w - 2, strWidth(l.text)));
+        const col = Math.max(1, Math.floor((w - strWidth(t)) / 2) + 1);
+        s += `${ESC.at(top + i + 1, col)}${l.style ?? ""}${t}${ESC.reset}`;
+    });
+    out.write(s);
+}
+/** Where to put the cube so it sits in the middle of this pane. */
+function cubePlacement() {
+    const w = out.columns ?? 80;
+    const h = out.rows ?? 24;
+    const size = cubeSize(w, h);
+    if (!size)
+        return { indent: 2, top: 0 };
+    return { indent: Math.max(2, Math.floor((w - size.w) / 2)), top: Math.max(0, Math.floor((h - size.h - 2) / 2)) };
+}
+async function welcome() {
+    setSessionOption("@cubes_current", "");
+    setSessionOption("@cubes_tab", "Cubes");
+    setPaneOption("@cubes_header", "#[bold]Cubes#[nobold] #[fg=colour240]·#[default] pick a session on the left");
+    let spin = null;
+    const draw = () => {
+        spin?.stop();
+        const { indent, top } = cubePlacement();
+        out.write(ESC.hideCursor + ESC.home + ESC.clear + "\n".repeat(top));
+        spin = new CubeSpinner(out, "Pick a session on the left", process.env, indent);
+    };
+    draw();
+    out.on("resize", draw);
+    for (;;) {
+        await waitKey((k) => k.kind === "ctrl-]" || k.kind === "escape" || k.kind === "tab");
+        focusList();
+    }
+}
+const OUTCOME_WORDS = {
+    ended: { head: "Session ended", key: "resume it", color: 242 },
+    disconnected: { head: "Disconnected", key: "reconnect", color: 214 },
+    refused: { head: "The server refused the attach", key: "try again", color: 203 },
+    detached: { head: "Detached", key: "attach again", color: 242 },
+};
+async function sessionPane(id) {
+    const api = makeApi(currentSession());
+    const copyCmd = clipboardWriter();
+    setSessionOption("@cubes_current", id);
+    let row = { id, title: null, status: "running", created_at: "" };
+    setHeader(row, { glyph: "◌", color: 80, label: "connecting" });
+    for (;;) {
+        let result;
+        try {
+            row = await api.get(`/sessions/${encodeURIComponent(id)}`);
+            setHeader(row);
+            const { indent, top } = cubePlacement();
+            out.write(ESC.home + ESC.clear + "\n".repeat(top));
+            row = await ensureRunning(api, row, true, out, indent);
+            setHeader(row);
+            result = await attach({
+                api,
+                host: currentSession().host,
+                openWs: (url, protocols) => new WebSocket(url, protocols),
+                stdin: process.stdin,
+                stdout: out,
+                stderr: out,
+                readClipboardImage: () => readClipboardImage(),
+                clipboard: copyCmd ? { write: (text) => writeClipboard(copyCmd, text) } : null,
+            }, row, {
+                onDetachKey: focusList,
+                onCopied: (text) => {
+                    setPaneOption("@cubes_header", `#[fg=colour78]✓ Copied ${[...text].length} characters to your clipboard#[default]`);
+                    setTimeout(() => setHeader(row), 1500);
+                },
+                status: { onRow: (r) => { row = { ...row, ...r }; setHeader(row); } },
+            });
+        }
+        catch (e) {
+            result = { code: 1, message: e.message, outcome: "disconnected" };
+        }
+        const words = OUTCOME_WORDS[result.outcome];
+        setHeader(row, { glyph: "○", color: words.color, label: words.head.toLowerCase() });
+        message([
+            { text: words.head, style: ESC.bold + ESC.fg(words.color) },
+            { text: result.message, style: ESC.dim },
+            { text: "" },
+            { text: `r  ${words.key}     ^]  back to the list` },
+        ]);
+        // Wait for the person: `r` goes round again, ^] / Esc / Tab hand focus back to the list.
+        for (;;) {
+            const k = await waitKey((k) => (k.kind === "char" && (k.ch === "r" || k.ch === "R")) || k.kind === "enter"
+                || k.kind === "ctrl-]" || k.kind === "escape" || k.kind === "tab");
+            if (k.kind === "char" || k.kind === "enter")
+                break;
+            focusList();
+        }
+    }
+}
+export async function runPane(id) {
+    for (const sig of ["SIGTERM", "SIGHUP"])
+        process.on(sig, () => process.exit(0));
+    process.on("exit", () => out.write(ESC.showCursor));
+    return id ? sessionPane(id) : welcome();
+}

package/dist/tui/term.js

@@ -0,0 +1,133 @@
+// The small amount of terminal the split view needs: how wide a string really is, how to cut one to a
+// column budget, and what the bytes a terminal sends for a key or a mouse click mean.
+/** Columns a code point occupies: 0 for combining marks and joiners, 2 for wide (CJK, emoji), else 1.
+ *  Not the whole of Unicode's East Asian Width table - the ranges that actually show up in session
+ *  titles and in our own glyphs. Getting this wrong shifts every column after the character. */
+export function cpWidth(cp) {
+    if (cp === 0)
+        return 0;
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0))
+        return 0;
+    if ((cp >= 0x300 && cp <= 0x36f) || cp === 0x200b || cp === 0x200c || cp === 0x200d ||
+        (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x1f3fb && cp <= 0x1f3ff) || (cp >= 0xe0100 && cp <= 0xe01ef))
+        return 0;
+    if ((cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3) ||
+        (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60) ||
+        (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x1f300 && cp <= 0x1f64f) || (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+        (cp >= 0x1f680 && cp <= 0x1f6ff) || (cp >= 0x2600 && cp <= 0x26ff && isEmojiPresentation(cp)) ||
+        cp === 0x270b || cp === 0x2705 || cp === 0x274c || (cp >= 0x20000 && cp <= 0x3fffd))
+        return 2;
+    return 1;
+}
+// The few symbols in U+2600-26FF that terminals draw two cells wide (emoji presentation by default).
+function isEmojiPresentation(cp) {
+    return [0x2614, 0x2615, 0x2648, 0x267f, 0x2693, 0x26a1, 0x26aa, 0x26ab, 0x26bd, 0x26be, 0x26c4, 0x26c5,
+        0x26ce, 0x26d4, 0x26ea, 0x26f2, 0x26f3, 0x26f5, 0x26fa, 0x26fd].includes(cp);
+}
+export function strWidth(s) {
+    let w = 0;
+    for (const ch of s)
+        w += cpWidth(ch.codePointAt(0));
+    return w;
+}
+/** Exactly `w` columns: cut with an ellipsis when too long, padded with spaces when short. */
+export function fit(s, w) {
+    if (w <= 0)
+        return "";
+    let out = "";
+    let used = 0;
+    const total = strWidth(s);
+    const budget = total > w ? w - 1 : w;
+    for (const ch of s) {
+        const cw = cpWidth(ch.codePointAt(0));
+        if (used + cw > budget)
+            break;
+        out += ch;
+        used += cw;
+    }
+    if (total > w) {
+        out += "…";
+        used += 1;
+    }
+    return out + " ".repeat(Math.max(0, w - used));
+}
+/** Nothing from the server may reach the screen as a control character. */
+export function printable(s) {
+    return s.replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+}
+const CSI_KEYS = {
+    A: "up", B: "down", C: "right", D: "left", H: "home", F: "end", Z: "backtab",
+};
+const TILDE_KEYS = {
+    "1": "home", "7": "home", "4": "end", "8": "end", "5": "pgup", "6": "pgdn",
+};
+/** Turn one read of raw input into keys. A lone ESC is the Escape key (tmux delivers a real escape
+ *  sequence in one read; the split view sets tmux's escape-time low so Escape is not held back). */
+export function parseKeys(input) {
+    const keys = [];
+    let i = 0;
+    while (i < input.length) {
+        const c = input[i];
+        if (c === "\x1b") {
+            const rest = input.slice(i);
+            const mouse = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/.exec(rest);
+            if (mouse) {
+                keys.push({ kind: "mouse", button: Number(mouse[1]), x: Number(mouse[2]), y: Number(mouse[3]), release: mouse[4] === "m" });
+                i += mouse[0].length;
+                continue;
+            }
+            const csi = /^\x1b[[O](\d*)(?:;\d+)*([A-Za-z~])/.exec(rest);
+            if (csi) {
+                const kind = csi[2] === "~" ? TILDE_KEYS[csi[1]] : CSI_KEYS[csi[2]];
+                if (kind)
+                    keys.push({ kind });
+                i += csi[0].length;
+                continue;
+            }
+            keys.push({ kind: "escape" });
+            i += 1;
+            continue;
+        }
+        i += 1;
+        if (c === "\r" || c === "\n")
+            keys.push({ kind: "enter" });
+        else if (c === "\t")
+            keys.push({ kind: "tab" });
+        else if (c === "\x7f" || c === "\b")
+            keys.push({ kind: "backspace" });
+        else if (c === "\x03")
+            keys.push({ kind: "ctrl-c" });
+        else if (c === "\x1d")
+            keys.push({ kind: "ctrl-]" });
+        else if (c === "\x0c")
+            keys.push({ kind: "ctrl-l" });
+        else if (c >= " ") {
+            // A surrogate pair is one character.
+            const cp = input.codePointAt(i - 1);
+            const ch = String.fromCodePoint(cp);
+            if (ch.length === 2)
+                i += 1;
+            keys.push({ kind: "char", ch });
+        }
+    }
+    return keys;
+}
+export const ESC = {
+    altOn: "\x1b[?1049h",
+    altOff: "\x1b[?1049l",
+    hideCursor: "\x1b[?25l",
+    showCursor: "\x1b[?25h",
+    mouseOn: "\x1b[?1000h\x1b[?1002h\x1b[?1006h",
+    mouseOff: "\x1b[?1000l\x1b[?1002l\x1b[?1006l",
+    syncOn: "\x1b[?2026h",
+    syncOff: "\x1b[?2026l",
+    home: "\x1b[H",
+    clear: "\x1b[2J",
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    inverse: "\x1b[7m",
+    fg: (n) => `\x1b[38;5;${n}m`,
+    bg: (n) => `\x1b[48;5;${n}m`,
+    at: (row, col) => `\x1b[${row};${col}H`,
+};

package/dist/tui/tmux.js

@@ -0,0 +1,49 @@
+// The local tmux the split view runs in: its own socket, so it never touches a tmux the person uses,
+// and every call synchronous - these are a handful of tiny commands, never a stream.
+import { spawnSync } from "node:child_process";
+export const SOCKET = "cubes-tui";
+export const SESSION = "cubes";
+/** Run `tmux -L cubes-tui <args>`. `TMUX` is dropped from the child's env: inside someone's own tmux
+ *  it would make every command refuse ("sessions should be nested with care"). */
+export function tmux(args, opts = {}) {
+    const env = { ...process.env };
+    delete env.TMUX;
+    const r = spawnSync("tmux", ["-L", SOCKET, ...args], { encoding: "utf8", env, input: opts.input });
+    if (r.error)
+        return { code: 127, out: "", err: r.error.message };
+    return { code: r.status ?? 1, out: (r.stdout ?? "").trim(), err: (r.stderr ?? "").trim() };
+}
+/** tmux's version as a number (3.3a -> 3.3), or null when there is no tmux at all. */
+export function tmuxVersion() {
+    const r = spawnSync("tmux", ["-V"], { encoding: "utf8" });
+    if (r.error || r.status !== 0)
+        return null;
+    const m = /(\d+)\.(\d+)/.exec(r.stdout ?? "");
+    return m ? Number(`${m[1]}.${m[2]}`) : null;
+}
+/** Single-quote for the `sh -c` tmux runs a pane's command through. */
+export function shq(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/** A tmux FORMAT is parsed for `#{...}` and `#[...]`; a session's title must never be either. */
+export function fmtText(s) {
+    return s.replace(/#/g, "##");
+}
+/** The command line that runs this same CLI (same node, same script) with `args`. */
+export function selfCommand(args) {
+    return [process.execPath, process.argv[1] ?? "", ...args].map(shq).join(" ");
+}
+/** Set a pane option on THIS pane (the one the calling process runs in). Best-effort: a header that
+ *  failed to update must never take the pane down. */
+export function setPaneOption(name, value) {
+    const pane = process.env.TMUX_PANE;
+    if (!pane)
+        return;
+    tmux(["set-option", "-p", "-t", pane, name, value]);
+}
+export function setSessionOption(name, value) {
+    tmux(["set-option", "-t", SESSION, name, value]);
+}
+export function getSessionOption(name) {
+    return tmux(["show-options", "-v", "-q", "-t", SESSION, name]).out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Attach to your Cubes sessions from your own terminal (Warp, iTerm, Ghostty, anything).",
   "type": "module",
   "bin": {