@hellix-ai/cubes 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# cubes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Attach to your [Cubes](https://cubes.hellix.ai) sessions from your own terminal (Warp, iTerm2, Ghostty,
+Terminal.app, anything) with your own font, colors and keyboard shortcuts.
+
+```sh
+npm install -g @hellix-ai/cubes      # needs Node.js 22.4+
+
+cubes login --host cubes.hellix.ai   # prints a code; approve it in the browser
+cubes ls                             # your sessions
+cubes attach                         # pick a running one
+cubes attach 7ff4                    # or name one: an id prefix, or part of its title
+```
+
+No install: `npx @hellix-ai/cubes attach <session>`.
+
+## While attached
+
+Every key goes to the session, exactly as if Claude Code were running locally, except:
+
+| key | does |
+| --- | --- |
+| `Ctrl-]` | detach. The session keeps running. |
+| `Ctrl-V` | paste the image on your clipboard: it is uploaded to the session and its path typed in (macOS, and Linux with `wl-paste` or `xclip`). With no image on the clipboard, Ctrl-V goes through unchanged. |
+
+**One keyboard per session.** Attaching takes the keyboard from any browser tab open on the same session
+(that tab becomes read-only, with a Take over button) and fits the session to your window. If someone
+takes it back, the terminal says so and goes read-only; detach and attach again to reclaim it.
+`cubes attach --view` watches without taking it.
+
+A stopped or hibernated session is resumed before attaching (`--no-resume` to refuse). A dropped
+connection reconnects on its own and replays the screen.
+
+Scrollback lives in the session's tmux: scroll with the mouse wheel or trackpad (tmux copy-mode), not
+your terminal's own scrollback.
+
+## Commands
+
+```
+cubes login [--host URL] [--org ALIAS] [--no-browser]
+cubes logout
+cubes whoami
+cubes org [ALIAS]
+cubes ls [--all] [--json]
+cubes attach [SESSION] [--view] [--no-resume]
+```
+
+`--org ALIAS` works on any command. If you belong to several organizations, `cubes org` lists them and
+`cubes org <alias>` changes the default.
+
+## Sign-in
+
+`cubes login` uses the OAuth device flow against your Cubes install's own sign-in: the CLI never sees your
+password. The login is stored in `~/.config/cubes/config.json` (mode 0600) and lasts until you
+`cubes logout`, which revokes it, or until it goes unused for 30 days.
+
+For scripts and CI, skip the stored login: set `CUBES_HOST`, `CUBES_TOKEN` (an access token) and
+optionally `CUBES_ORG`.

package/dist/api.js

@@ -0,0 +1,58 @@
+// The REST half: the same routes the web app calls, with the same Bearer + `x-org` pair.
+import { CliError } from "./auth.js";
+export function makeApi(s, fetchImpl = fetch) {
+    async function call(method, path, body, init) {
+        const send = async (force) => {
+            const headers = { authorization: `Bearer ${await s.token(force)}` };
+            if (s.org)
+                headers["x-org"] = s.org;
+            let payload;
+            if (init?.raw) {
+                headers["content-type"] = init.contentType ?? "application/octet-stream";
+                payload = init.raw;
+            }
+            else if (body !== undefined) {
+                headers["content-type"] = "application/json";
+                payload = JSON.stringify(body);
+            }
+            try {
+                return await fetchImpl(`${s.host}/api${path}`, { method, headers, body: payload });
+            }
+            catch (e) {
+                throw new CliError(`cannot reach ${s.host}: ${e.message}`);
+            }
+        };
+        let res = await send(false);
+        // A token the server refuses may simply be one our clock thinks is still good. One forced
+        // refresh, then the refusal stands.
+        if (res.status === 401)
+            res = await send(true);
+        const text = await res.text();
+        let data = undefined;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch { /* not JSON */ }
+        if (!res.ok) {
+            const msg = data?.error;
+            throw new ApiError(res.status, typeof msg === "string" ? msg : `HTTP ${res.status}`, path);
+        }
+        return data;
+    }
+    return {
+        get: (path) => call("GET", path),
+        post: (path, body, init) => call("POST", path, body, init),
+    };
+}
+export class ApiError extends CliError {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(status === 400 && /organization/.test(message)
+            ? `${message} - pick one with \`cubes org <alias>\``
+            : message);
+        this.status = status;
+        this.path = path;
+        this.name = "ApiError";
+    }
+}

package/dist/args.js

@@ -0,0 +1,37 @@
+// Argument parsing, small enough not to need a dependency.
+import { CliError } from "./auth.js";
+/** Flags that take a value (`--host X` or `--host=X`); every other flag is a switch. */
+const VALUED = new Set(["host", "org"]);
+export function parseArgs(argv) {
+    const pos = [];
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h") {
+            flags.set("help", true);
+            continue;
+        }
+        if (a === "-v") {
+            flags.set("version", true);
+            continue;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+            if (eq > 0)
+                flags.set(name, a.slice(eq + 1));
+            else if (VALUED.has(name)) {
+                const v = argv[i + 1];
+                if (v === undefined || v.startsWith("--"))
+                    throw new CliError(`--${name} needs a value`);
+                flags.set(name, v);
+                i++;
+            }
+            else
+                flags.set(name, true);
+            continue;
+        }
+        pos.push(a);
+    }
+    return { cmd: pos.shift(), pos, flags };
+}

package/dist/attach.js

@@ -0,0 +1,318 @@
+// The bridge: your terminal <-> the session's live TTY, over the same websocket the web terminal uses.
+//
+// The wire (server/src/ws.ts + engine/tty.ts) is already exactly what a terminal needs:
+//   • the upgrade carries a single-use ~30s ticket as the SECOND subprotocol, after the constant
+//     `cube.tty.v1` (the server echoes only the marker, never the secret);
+//   • BINARY frames are raw terminal bytes - our keystrokes in, the screen out;
+//   • TEXT frames are JSON control: we send {type:'resize'|'takeover'}, the server sends
+//     {type:'role', writer, cols, rows} and {type:'resize', cols, rows}.
+// So there is nothing to emulate here. Raw mode on, bytes both ways, a resize on SIGWINCH.
+//
+// ONE KEYBOARD PER SESSION. The server gives the writer token to the first viewer and makes every
+// later one a read-only mirror. Someone who runs `cubes attach` means to type, so unless `--view` is
+// passed we send `takeover` the moment we are told we are a mirror - the same button the web shows
+// on a read-only tile. The writer also decides the pane's size, so the session re-fits to THIS window.
+import { ApiError } from "./api.js";
+import { InputFilter, PASTE_IMAGE_BYTE } from "./keys.js";
+export const TTY_SUBPROTOCOL = "cube.tty.v1";
+const OPEN = 1;
+/** Close codes (server/src/engine/tty.ts, web/src/cubes/Terminal.tsx). */
+const WS_CLOSE_BACKPRESSURE = 4001;
+const WS_CLOSE_FULL = 4002;
+const WS_CLOSE_PARKED = 4004;
+const WS_CLOSE_UNAUTHORIZED = 4403;
+/** Drops that mean "the session is fine, the socket is not": re-mint a ticket and re-attach; the
+ *  server replays its scrollback ring. 1001/1012/1013 are a server going away or restarting. */
+const TRANSIENT = new Set([WS_CLOSE_BACKPRESSURE, 1001, 1005, 1006, 1011, 1012, 1013]);
+const DEFAULT_BACKOFF = [300, 600, 1200, 2400, 5000, 5000, 5000, 5000];
+/** Everything an attached session may have switched on in YOUR terminal (mouse reporting, bracketed
+ *  paste, focus events, app cursor keys, kitty/modifyOtherKeys keyboard modes, a hidden cursor, a
+ *  scroll region) - switched back off on the way out, so detaching never leaves Warp/iTerm in a
+ *  state where the wheel prints garbage. */
+export const RESTORE_TERMINAL = "\x1b[0m\x1b[?25h\x1b[0 q\x1b[r" +
+    "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l" +
+    "\x1b[?2004l\x1b[?1004l\x1b[?1l\x1b>\x1b[<u\x1b[>4;0m";
+const ENTER_ALT = "\x1b[?1049h\x1b[H\x1b[2J";
+const LEAVE_ALT = "\x1b[?1049l";
+const CLEAR = "\x1b[H\x1b[2J";
+export function wsUrlFor(host, id) {
+    return `${host.replace(/^http/i, "ws")}/api/sessions/${encodeURIComponent(id)}/tty`;
+}
+export function attach(deps, session, opts = {}) {
+    const { api, stdin, stdout, stderr } = deps;
+    const backoff = opts.backoffMs ?? DEFAULT_BACKOFF;
+    const filter = new InputFilter({ pasteImage: !opts.view });
+    const enc = new TextEncoder();
+    return new Promise((resolve) => {
+        let ws = null;
+        let role = null;
+        let askedTakeover = false;
+        let takeoverPending = false;
+        /** Someone took the keyboard FROM us. Sticky for the whole attach, reconnects included: a person
+         *  who clicked "take over" in the browser must not have it snatched back by a network blip. */
+        let yielded = false;
+        let entered = false;
+        let done = false;
+        let attempts = 0;
+        let timer = null;
+        // Keystrokes that must wait their turn: until the server says who holds the keyboard, and while
+        // an image paste is uploading (so what is typed after Ctrl-V lands after the path, not before).
+        let pending = [];
+        let pasting = false;
+        const note = (msg) => {
+            stderr.write(entered ? `\r\n\x1b[2m[cubes] ${msg}\x1b[0m\r\n` : `[cubes] ${msg}\n`);
+        };
+        const enter = () => {
+            if (entered)
+                return;
+            entered = true;
+            if (stdin.isTTY)
+                stdin.setRawMode?.(true);
+            stdout.write(ENTER_ALT);
+        };
+        const finish = (code, message) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            stdin.off("data", onData);
+            stdout.off("resize", onResize);
+            const sock = ws;
+            ws = null;
+            if (sock) {
+                sock.onclose = null;
+                sock.onmessage = null;
+                try {
+                    sock.close(1000, "detached");
+                }
+                catch { /* already gone */ }
+            }
+            if (entered) {
+                stdout.write(RESTORE_TERMINAL + LEAVE_ALT);
+                if (stdin.isTTY)
+                    stdin.setRawMode?.(false);
+            }
+            stdin.pause();
+            resolve({ code, message });
+        };
+        const sendRaw = (b) => {
+            if (ws && ws.readyState === OPEN)
+                ws.send(b);
+        };
+        // Hold keys while we cannot yet say where they go: before the first role, while our takeover is
+        // in flight (a mirror that asked for the keyboard is about to be the writer), and mid-paste.
+        const holding = () => role === null || (role === "mirror" && takeoverPending) || pasting;
+        const flushPending = () => {
+            if (holding())
+                return;
+            const q = pending;
+            pending = [];
+            if (role === "writer")
+                for (const b of q)
+                    sendRaw(b);
+        };
+        const sendInput = (b) => {
+            if (opts.view)
+                return;
+            if (holding()) {
+                if (pending.reduce((n, x) => n + x.length, 0) < 64 * 1024)
+                    pending.push(b.slice());
+                return;
+            }
+            if (role === "writer")
+                sendRaw(b);
+        };
+        const sendResize = () => {
+            const cols = stdout.columns ?? 80;
+            const rows = stdout.rows ?? 24;
+            if (ws && ws.readyState === OPEN)
+                ws.send(JSON.stringify({ type: "resize", cols, rows }));
+        };
+        const pasteImage = async () => {
+            pasting = true;
+            let typed = Uint8Array.of(PASTE_IMAGE_BYTE);
+            try {
+                const img = await deps.readClipboardImage();
+                if (img) {
+                    note(`uploading the image on your clipboard (${Math.ceil(img.bytes.length / 1024)} KB)…`);
+                    const r = await api.post(`/sessions/${encodeURIComponent(session.id)}/paste-image`, undefined, { contentType: img.type, raw: img.bytes });
+                    // A trailing space so the person can keep typing after the path - the web does the same.
+                    typed = enc.encode(r.path + " ");
+                }
+            }
+            catch (e) {
+                note(`image paste failed: ${e.message}`);
+                typed = new Uint8Array(0);
+            }
+            finally {
+                pasting = false;
+            }
+            if (done)
+                return;
+            if (typed.length) {
+                if (role === "writer")
+                    sendRaw(typed);
+                else
+                    pending.unshift(typed);
+            }
+            flushPending();
+        };
+        function onData(chunk) {
+            for (const a of filter.feed(chunk)) {
+                if (a.kind === "detach") {
+                    finish(0, "detached");
+                    return;
+                }
+                if (a.kind === "paste-image") {
+                    if (pasting)
+                        continue;
+                    void pasteImage();
+                    continue;
+                }
+                sendInput(a.bytes);
+            }
+        }
+        function onResize() { sendResize(); }
+        const retry = (ms) => {
+            if (done)
+                return;
+            timer = setTimeout(() => { timer = null; void connect(); }, ms);
+        };
+        const onClose = (code, reason) => {
+            ws = null;
+            role = null;
+            if (done)
+                return;
+            if (code === 1000) {
+                finish(0, reason ? `session ended (${reason})` : "session ended");
+                return;
+            }
+            if (code === WS_CLOSE_UNAUTHORIZED) {
+                finish(1, "the server refused the attach - your sign-in or org membership may have changed");
+                return;
+            }
+            if (code === WS_CLOSE_PARKED) {
+                note("this session's terminal is parked (its machine stopped answering). Waiting for it to come back - Ctrl-] to give up.");
+                retry(opts.parkedRetryMs ?? 15_000);
+                return;
+            }
+            if (code === WS_CLOSE_FULL) {
+                note("this session already has the most viewers it allows - waiting for one to leave. Ctrl-] to give up.");
+                retry(opts.fullRetryMs ?? 5_000);
+                return;
+            }
+            if (TRANSIENT.has(code) && attempts < backoff.length) {
+                const ms = backoff[attempts];
+                attempts += 1;
+                note(`connection dropped (${code}) - reconnecting (${attempts}/${backoff.length})…`);
+                retry(ms);
+                return;
+            }
+            finish(1, TRANSIENT.has(code)
+                ? "lost the connection to the session and could not get it back"
+                : `the session closed the connection (${code}${reason ? ` ${reason}` : ""})`);
+        };
+        const connect = async () => {
+            if (done)
+                return;
+            let ticket;
+            try {
+                ticket = (await api.post(`/sessions/${encodeURIComponent(session.id)}/terminal/ticket`)).ticket;
+            }
+            catch (e) {
+                if (done)
+                    return;
+                if (e instanceof ApiError && e.status === 409) {
+                    finish(1, "the session is not running any more");
+                    return;
+                }
+                if (e instanceof ApiError && e.status < 500) {
+                    finish(1, e.message);
+                    return;
+                }
+                // The server itself is restarting or unreachable: same ladder as a dropped socket.
+                if (attempts < backoff.length) {
+                    const ms = backoff[attempts];
+                    attempts += 1;
+                    note(`${e.message} - retrying (${attempts}/${backoff.length})…`);
+                    retry(ms);
+                    return;
+                }
+                finish(1, e.message);
+                return;
+            }
+            if (done)
+                return;
+            const sock = deps.openWs(wsUrlFor(deps.host, session.id), [TTY_SUBPROTOCOL, ticket]);
+            sock.binaryType = "arraybuffer";
+            ws = sock;
+            askedTakeover = false;
+            takeoverPending = false;
+            sock.onopen = () => {
+                if (ws !== sock)
+                    return;
+                if (!entered)
+                    enter();
+                else
+                    stdout.write(CLEAR); // the server replays its ring; paint it on a clean screen
+                sendResize();
+            };
+            sock.onmessage = (ev) => {
+                if (ws !== sock)
+                    return;
+                const data = ev.data;
+                if (typeof data === "string") {
+                    let msg;
+                    try {
+                        msg = JSON.parse(data);
+                    }
+                    catch {
+                        return;
+                    }
+                    if (msg.type === "role") {
+                        // A role is what proves the attach stuck (the viewer-cap refusal arrives AFTER open),
+                        // so this - not onopen - is where the reconnect ladder resets.
+                        attempts = 0;
+                        const prev = role;
+                        role = msg.writer ? "writer" : "mirror";
+                        if (role === "mirror" && prev === "writer") {
+                            // Demoted: another viewer took the keyboard. Never take it back automatically - two
+                            // terminals that each did would pass it back and forth forever.
+                            yielded = true;
+                            takeoverPending = false;
+                            note("someone else took the keyboard - this terminal is read-only now. Ctrl-] and attach again to take it back.");
+                        }
+                        else if (role === "mirror" && !opts.view && !askedTakeover && !yielded) {
+                            askedTakeover = true;
+                            takeoverPending = true;
+                            sock.send(JSON.stringify({ type: "takeover" }));
+                        }
+                        if (role === "writer") {
+                            takeoverPending = false;
+                            sendResize(); // the pane now sizes to us
+                        }
+                        flushPending();
+                    }
+                    return;
+                }
+                if (data instanceof ArrayBuffer)
+                    stdout.write(new Uint8Array(data));
+                else if (ArrayBuffer.isView(data))
+                    stdout.write(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+            };
+            sock.onclose = (ev) => { if (ws === sock)
+                onClose(ev.code, ev.reason); };
+            sock.onerror = () => { };
+        };
+        stdin.on("data", onData);
+        stdout.on("resize", onResize);
+        stdin.resume();
+        if (opts.signal?.aborted) {
+            finish(0, "detached");
+            return;
+        }
+        opts.signal?.addEventListener("abort", () => finish(0, "detached"), { once: true });
+        void connect();
+    });
+}

package/dist/auth.js

@@ -0,0 +1,206 @@
+// Signing in: the OAuth 2.0 Device Authorization Grant (RFC 8628) against the app's own Keycloak.
+//
+// The CLI is told nothing but the app's URL. `/api/client-config` names the realm issuer and the
+// public client (`cubes-cli`), the issuer's discovery document names the endpoints, and the person
+// approves a short code in the browser where they are already signed in. So the CLI never sees a
+// password, a Google login never has to happen inside a terminal, and the same binary works against
+// any install.
+//
+// It asks for `offline_access`: a laptop CLI is used in bursts days apart, and an ordinary refresh
+// token dies with the browser-length SSO session. `cubes logout` revokes the offline token.
+import { loadLogin, saveLogin } from "./config.js";
+export const SCOPE = "openid profile email organization offline_access";
+/** Refresh this long before the access token actually expires, so a request never races the edge. */
+const EXP_SKEW_S = 60;
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}
+export function normalizeHost(raw) {
+    let h = raw.trim();
+    if (!/^https?:\/\//i.test(h))
+        h = `https://${h}`;
+    const u = new URL(h);
+    return u.origin;
+}
+/** The payload of a JWT, unverified. Only ever used to read OUR OWN token's exp + display claims -
+ *  the server verifies every token it is handed; nothing here makes an authorization decision. */
+export function decodeJwt(token) {
+    const part = token.split(".")[1];
+    if (!part)
+        return {};
+    try {
+        return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The org aliases a token is a member of. Keycloak's membership mapper emits a flat string array;
+ *  it can also be configured to emit an object keyed by alias, so both are read. */
+export function orgsOf(token) {
+    const c = decodeJwt(token).organization;
+    if (Array.isArray(c))
+        return c.filter((x) => typeof x === "string");
+    if (c && typeof c === "object")
+        return Object.keys(c);
+    return [];
+}
+export function whoOf(token) {
+    const p = decodeJwt(token);
+    const name = p.preferred_username ?? p.email ?? p.sub;
+    return typeof name === "string" ? name : "unknown";
+}
+async function json(res, what) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${what}: HTTP ${res.status} (not JSON)`);
+    }
+}
+export async function discover(host) {
+    let res;
+    try {
+        res = await fetch(`${host}/api/client-config`);
+    }
+    catch (e) {
+        throw new CliError(`cannot reach ${host}: ${e.message}`);
+    }
+    if (!res.ok)
+        throw new CliError(`${host} did not answer /api/client-config (HTTP ${res.status}) - is that a Cubes URL?`);
+    const cfg = await json(res, "client-config");
+    if (cfg.cli === undefined)
+        throw new CliError(`${host} is too old for the CLI (no login settings in /api/client-config)`);
+    if (cfg.cli === null)
+        throw new CliError(`${host} has no sign-in configured`);
+    const wk = await fetch(`${cfg.cli.issuer}/.well-known/openid-configuration`);
+    if (!wk.ok)
+        throw new CliError(`cannot read the sign-in settings at ${cfg.cli.issuer} (HTTP ${wk.status})`);
+    const d = await json(wk, "openid-configuration");
+    if (!d.device_authorization_endpoint)
+        throw new CliError("this install's sign-in does not support device login");
+    return {
+        issuer: cfg.cli.issuer,
+        clientId: cfg.cli.clientId,
+        endpoints: { token: d.token_endpoint, device: d.device_authorization_endpoint, revoke: d.revocation_endpoint },
+    };
+}
+export async function startDevice(d) {
+    const res = await fetch(d.endpoints.device, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ client_id: d.clientId, scope: SCOPE }),
+    });
+    const body = await json(res, "device login");
+    if (!res.ok || !body.device_code) {
+        throw new CliError(`device login refused: ${body.error_description ?? body.error ?? `HTTP ${res.status}`}`);
+    }
+    return body;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Poll the token endpoint until the person approves (or refuses, or the code expires). */
+export async function pollDevice(d, start) {
+    let interval = Math.max(1, start.interval ?? 5) * 1000;
+    const deadline = Date.now() + start.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const res = await fetch(d.endpoints.token, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: start.device_code,
+                client_id: d.clientId,
+            }),
+        });
+        const t = await json(res, "token");
+        if (res.ok && t.access_token)
+            return t;
+        if (t.error === "authorization_pending")
+            continue;
+        if (t.error === "slow_down") {
+            interval += 5000;
+            continue;
+        }
+        if (t.error === "access_denied")
+            throw new CliError("sign-in was declined in the browser");
+        if (t.error === "expired_token")
+            break;
+        throw new CliError(`sign-in failed: ${t.error_description ?? t.error ?? `HTTP ${res.status}`}`);
+    }
+    throw new CliError("the code expired before it was approved - run `cubes login` again");
+}
+export function loginFromTokens(host, d, t, org) {
+    if (!t.access_token || !t.refresh_token)
+        throw new CliError("sign-in returned no tokens");
+    const exp = decodeJwt(t.access_token).exp;
+    return {
+        host, issuer: d.issuer, clientId: d.clientId, endpoints: d.endpoints,
+        refreshToken: t.refresh_token, accessToken: t.access_token,
+        accessExp: typeof exp === "number" ? exp : Math.floor(Date.now() / 1000) + (t.expires_in ?? 300),
+        org,
+    };
+}
+export async function refresh(login) {
+    const res = await fetch(login.endpoints.token, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: login.refreshToken, client_id: login.clientId }),
+    });
+    const t = await json(res, "token refresh");
+    if (!res.ok || !t.access_token) {
+        throw new CliError(`your sign-in to ${login.host} has expired or was revoked - run \`cubes login\``);
+    }
+    const exp = decodeJwt(t.access_token).exp;
+    return {
+        ...login,
+        accessToken: t.access_token,
+        // Keycloak may or may not rotate; keep the old one when it does not send a new one.
+        refreshToken: t.refresh_token ?? login.refreshToken,
+        accessExp: typeof exp === "number" ? exp : Math.floor(Date.now() / 1000) + (t.expires_in ?? 300),
+    };
+}
+export async function revoke(login) {
+    if (!login.endpoints.revoke)
+        return;
+    await fetch(login.endpoints.revoke, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ token: login.refreshToken, token_type_hint: "refresh_token", client_id: login.clientId }),
+    }).catch(() => undefined);
+}
+/** The login a command runs under. `CUBES_TOKEN` (+ `CUBES_HOST`, `CUBES_ORG`) bypasses the stored
+ *  login entirely - for CI and scripts, where nobody is there to approve a device code. */
+export function currentSession(opts = {}, env = process.env) {
+    if (env.CUBES_TOKEN) {
+        const tok = env.CUBES_TOKEN;
+        if (!env.CUBES_HOST)
+            throw new CliError("CUBES_TOKEN needs CUBES_HOST too");
+        const host = normalizeHost(env.CUBES_HOST);
+        const org = opts.org || env.CUBES_ORG || orgsOf(tok)[0];
+        return { host, org, token: async () => tok, who: () => whoOf(tok) };
+    }
+    let login = loadLogin();
+    if (!login)
+        throw new CliError("not signed in - run `cubes login --host <your Cubes URL>`");
+    const org = opts.org || env.CUBES_ORG || login.org;
+    return {
+        host: login.host,
+        org,
+        async token(force = false) {
+            const now = Math.floor(Date.now() / 1000);
+            if (!force && login.accessToken && (login.accessExp ?? 0) - EXP_SKEW_S > now)
+                return login.accessToken;
+            login = await refresh(login);
+            saveLogin(login);
+            return login.accessToken;
+        },
+        who: () => (login.accessToken ? whoOf(login.accessToken) : "unknown"),
+    };
+}

package/dist/cli.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// `cubes` - your Cubes sessions in your own terminal.
+//
+//   cubes login --host https://your-cubes   sign in (device code, approved in the browser)
+//   cubes ls                                 list sessions
+//   cubes attach [session]                   attach this terminal to a session (Ctrl-] detaches)
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline/promises";
+import { makeApi, ApiError } from "./api.js";
+import { attach, RESTORE_TERMINAL } from "./attach.js";
+import { CliError, currentSession, discover, loginFromTokens, normalizeHost, orgsOf, pollDevice, revoke, startDevice, whoOf, } from "./auth.js";
+import { readClipboardImage } from "./clipboard.js";
+import { clearLogin, configPath, loadLogin, saveLogin } from "./config.js";
+import { parseArgs } from "./args.js";
+import { formatTable, isUuid, listSessions, LIVE, resolveSession, stateOf } from "./sessions.js";
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+const HELP = `cubes ${VERSION} - attach to your Cubes sessions from your own terminal
+
+Usage:
+  cubes login [--host URL] [--org ALIAS] [--no-browser]   sign in with a code you approve in the browser
+  cubes logout                                            sign out and revoke this computer's login
+  cubes whoami                                            who, where, and which org
+  cubes org [ALIAS]                                       list your orgs, or switch the default
+  cubes ls [--all] [--json]                               list sessions (--all includes spawned ones)
+  cubes attach [SESSION] [--view] [--no-resume]           attach to a session
+
+SESSION is an id, the start of one (4+ characters), or part of its title. Left out, you pick from
+the running sessions. A stopped or hibernated session is resumed first unless --no-resume.
+
+While attached, every key goes to the session except:
+  Ctrl-]   detach (the session keeps running)
+  Ctrl-V   paste the image on your clipboard (uploaded, then its path is typed in)
+
+Attaching takes the keyboard from any browser tab on the same session (it becomes read-only) and
+fits the session to this window. --view watches without taking it.
+
+Global: --org ALIAS overrides the default org for one command.
+Env:    CUBES_HOST + CUBES_TOKEN (+ CUBES_ORG) use a token instead of the stored login.
+Config: ${configPath()}
+`;
+function str(f, name) {
+    const v = f.get(name);
+    return typeof v === "string" ? v : undefined;
+}
+const isTTY = () => !!process.stdin.isTTY && !!process.stdout.isTTY;
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function pick(items, label, question) {
+    for (let i = 0; i < items.length; i++)
+        process.stderr.write(`${label(items[i], i)}\n`);
+    const answer = await ask(question);
+    const n = Number(answer);
+    if (!Number.isInteger(n) || n < 1 || n > items.length)
+        throw new CliError("no choice made");
+    return items[n - 1];
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? ["open", url]
+        : process.platform === "win32" ? ["cmd", "/c", "start", "", url]
+            : (process.env.DISPLAY || process.env.WAYLAND_DISPLAY) ? ["xdg-open", url] : null;
+    if (!cmd)
+        return;
+    try {
+        spawn(cmd[0], cmd.slice(1), { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+    }
+    catch { /* the URL is printed anyway */ }
+}
+async function cmdLogin(a) {
+    const existing = loadLogin();
+    let raw = str(a.flags, "host") ?? process.env.CUBES_HOST ?? existing?.host;
+    if (!raw) {
+        if (!isTTY())
+            throw new CliError("which Cubes? `cubes login --host https://…`");
+        raw = await ask("Cubes URL (the address you open in the browser): ");
+        if (!raw)
+            throw new CliError("no URL given");
+    }
+    const host = normalizeHost(raw);
+    const d = await discover(host);
+    const start = await startDevice(d);
+    const url = start.verification_uri_complete ?? start.verification_uri;
+    process.stderr.write(`\nTo sign in to ${host}, open:\n\n  ${url}\n\nand confirm the code  ${start.user_code}\n\n`);
+    if (!a.flags.has("no-browser"))
+        openBrowser(url);
+    process.stderr.write("Waiting for approval…\n");
+    const tokens = await pollDevice(d, start);
+    const orgs = orgsOf(tokens.access_token);
+    let org = str(a.flags, "org");
+    if (org && orgs.length && !orgs.includes(org))
+        throw new CliError(`you are not a member of "${org}" (you are in: ${orgs.join(", ")})`);
+    if (!org) {
+        if (orgs.length === 1)
+            org = orgs[0];
+        else if (orgs.length > 1) {
+            org = isTTY()
+                ? await pick(orgs, (o, i) => `  ${i + 1}) ${o}`, "Which org should commands use by default? ")
+                : orgs[0];
+        }
+    }
+    saveLogin(loginFromTokens(host, d, tokens, org));
+    process.stderr.write(`Signed in to ${host} as ${whoOf(tokens.access_token)}${org ? `, org ${org}` : ""}.\n`);
+    if (!orgs.length)
+        process.stderr.write("You are not a member of any organization yet, so there is nothing to attach to.\n");
+    else if (orgs.length > 1)
+        process.stderr.write("Switch orgs any time with `cubes org <alias>`.\n");
+}
+async function cmdLogout() {
+    const login = loadLogin();
+    if (!login) {
+        process.stderr.write("Not signed in.\n");
+        return;
+    }
+    await revoke(login);
+    clearLogin();
+    process.stderr.write(`Signed out of ${login.host}.\n`);
+}
+async function cmdWhoami(a) {
+    const s = currentSession({ org: str(a.flags, "org") });
+    await s.token();
+    process.stdout.write(`${s.who()} @ ${s.host}${s.org ? ` (org ${s.org})` : ""}\n`);
+}
+async function cmdOrg(a) {
+    const s = currentSession();
+    const orgs = orgsOf(await s.token());
+    const want = a.pos[0];
+    if (want && process.env.CUBES_TOKEN)
+        throw new CliError("`cubes org <alias>` changes the stored login; with CUBES_TOKEN, set CUBES_ORG instead");
+    if (!want) {
+        if (!orgs.length) {
+            process.stderr.write("You are not a member of any organization.\n");
+            return;
+        }
+        for (const o of orgs)
+            process.stdout.write(`${o === s.org ? "*" : " "} ${o}\n`);
+        return;
+    }
+    if (!orgs.includes(want))
+        throw new CliError(`you are not a member of "${want}" (you are in: ${orgs.join(", ") || "none"})`);
+    const login = loadLogin();
+    saveLogin({ ...login, org: want });
+    process.stderr.write(`Default org is now ${want}.\n`);
+}
+async function cmdLs(a) {
+    const api = makeApi(currentSession({ org: str(a.flags, "org") }));
+    const rows = await listSessions(api, { all: a.flags.has("all") });
+    if (a.flags.has("json")) {
+        process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+        return;
+    }
+    if (!rows.length) {
+        process.stderr.write("No sessions.\n");
+        return;
+    }
+    process.stdout.write(formatTable(rows, process.stdout.columns ?? 120) + "\n");
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Bring a stopped/hibernated session back and wait until its terminal can be attached. */
+async function ensureRunning(api, row, resume) {
+    const id = encodeURIComponent(row.id);
+    let s = row;
+    if (s.status === "running")
+        return s;
+    if (!LIVE.has(s.status)) {
+        if (!resume)
+            throw new CliError(`that session is ${s.status}; leave out --no-resume to bring it back`);
+        process.stderr.write(`Resuming "${s.title ?? s.id}"…\n`);
+        try {
+            await api.post(`/sessions/${id}/resume`);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.status === 409 && /already running/.test(e.message)))
+                throw e;
+        }
+    }
+    let lastNote = "";
+    const deadline = Date.now() + 5 * 60_000;
+    while (Date.now() < deadline) {
+        s = await api.get(`/sessions/${id}`);
+        if (s.status === "running")
+            return s;
+        if (!LIVE.has(s.status))
+            throw new CliError(`the session stopped while starting (${s.status})`);
+        const note = s.provision_note
+            ? `${s.provision_note}${s.provision_total ? ` (${s.provision_done ?? 0}/${s.provision_total})` : ""}`
+            : "starting";
+        if (note !== lastNote) {
+            process.stderr.write(`  ${note}…\n`);
+            lastNote = note;
+        }
+        await sleep(1000);
+    }
+    throw new CliError("the session is taking too long to start - check it in the browser");
+}
+async function cmdAttach(a) {
+    const s = currentSession({ org: str(a.flags, "org") });
+    const api = makeApi(s);
+    const query = a.pos.join(" ").trim();
+    let row;
+    if (query && isUuid(query)) {
+        row = await api.get(`/sessions/${encodeURIComponent(query)}`);
+    }
+    else if (query) {
+        row = resolveSession(await listSessions(api, { all: true }), query);
+    }
+    else {
+        if (!isTTY())
+            throw new CliError("which session? `cubes attach <id or title>`");
+        const live = (await listSessions(api)).filter((r) => LIVE.has(r.status));
+        if (!live.length)
+            throw new CliError("no running sessions - `cubes ls` shows the rest; attach to one by id to resume it");
+        row = await pick(live, (r, i) => `  ${String(i + 1).padStart(2)}) ${r.id.slice(0, 8)}  ${stateOf(r).padEnd(8)} ${r.title ?? "(untitled)"}`, "Attach to which session? ");
+    }
+    if (!isTTY())
+        throw new CliError("attach needs an interactive terminal");
+    row = await ensureRunning(api, row, !a.flags.has("no-resume"));
+    const view = a.flags.has("view");
+    process.stderr.write(`Attaching to "${row.title ?? row.id}" (${row.id.slice(0, 8)})${view ? ", read-only" : ""}. Ctrl-] detaches.\n`);
+    const ac = new AbortController();
+    for (const sig of ["SIGTERM", "SIGHUP"])
+        process.on(sig, () => ac.abort());
+    // Whatever happens, never leave the person's terminal in raw mode on the alt screen.
+    process.on("uncaughtException", (e) => {
+        process.stdout.write(RESTORE_TERMINAL + "\x1b[?1049l");
+        try {
+            process.stdin.setRawMode?.(false);
+        }
+        catch { /* not a tty */ }
+        process.stderr.write(`cubes: ${e.message}\n`);
+        process.exit(1);
+    });
+    const result = await attach({
+        api,
+        host: s.host,
+        openWs: (url, protocols) => new WebSocket(url, protocols),
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        readClipboardImage: () => readClipboardImage(),
+    }, row, { view, signal: ac.signal });
+    process.stderr.write(`[cubes] ${result.message}\n`);
+    return result.code;
+}
+async function main(argv) {
+    if (typeof WebSocket === "undefined") {
+        throw new CliError(`cubes needs Node.js 22.4 or newer (this is ${process.version}) - it uses Node's built-in WebSocket`);
+    }
+    const a = parseArgs(argv);
+    if (a.flags.has("version")) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    if (!a.cmd || a.cmd === "help" || a.flags.has("help")) {
+        process.stdout.write(HELP);
+        return a.cmd || a.flags.has("help") ? 0 : 1;
+    }
+    switch (a.cmd) {
+        case "login":
+            await cmdLogin(a);
+            return 0;
+        case "logout":
+            await cmdLogout();
+            return 0;
+        case "whoami":
+            await cmdWhoami(a);
+            return 0;
+        case "org":
+        case "orgs":
+            await cmdOrg(a);
+            return 0;
+        case "ls":
+        case "list":
+            await cmdLs(a);
+            return 0;
+        case "attach":
+        case "a": return cmdAttach(a);
+        default: throw new CliError(`unknown command "${a.cmd}" - see \`cubes help\``);
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    process.stderr.write(`cubes: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(e instanceof CliError ? e.exitCode : 1);
+});

package/dist/clipboard.js

@@ -0,0 +1,67 @@
+// Read an IMAGE off the local clipboard, the way Claude Code does when it runs on your machine.
+//
+// macOS: AppleScript coerces whatever the pasteboard holds (a screenshot, an image copied from a
+// browser) to PNG and writes it to a temp file. Linux: wl-paste on Wayland, xclip on X11. Anything
+// else, or no image there, is null - and the caller then sends Ctrl-V through untouched.
+import { execFile } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function run(cmd, args) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 5000, maxBuffer: 32 * 1024 * 1024, encoding: "buffer" }, (err, stdout) => {
+            resolve(err ? null : stdout);
+        });
+    });
+}
+async function macos() {
+    const info = await run("osascript", ["-e", "clipboard info"]);
+    if (!info || !/PNGf|TIFF|JPEG|GIF/i.test(info.toString("utf8")))
+        return null;
+    const dir = mkdtempSync(join(tmpdir(), "cubes-paste-"));
+    const file = join(dir, "clip.png");
+    try {
+        const ok = await run("osascript", [
+            "-e", "set png_data to (the clipboard as «class PNGf»)",
+            "-e", `set fp to open for access POSIX file "${file}" with write permission`,
+            "-e", "write png_data to fp",
+            "-e", "close access fp",
+        ]);
+        if (!ok)
+            return null;
+        const bytes = readFileSync(file);
+        return bytes.length ? { bytes, type: "image/png" } : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function linux(env) {
+    if (env.WAYLAND_DISPLAY) {
+        const types = await run("wl-paste", ["--list-types"]);
+        if (types && /^image\/png$/m.test(types.toString("utf8"))) {
+            const b = await run("wl-paste", ["--no-newline", "--type", "image/png"]);
+            if (b?.length)
+                return { bytes: b, type: "image/png" };
+        }
+    }
+    if (env.DISPLAY) {
+        const targets = await run("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"]);
+        if (targets && /^image\/png$/m.test(targets.toString("utf8"))) {
+            const b = await run("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]);
+            if (b?.length)
+                return { bytes: b, type: "image/png" };
+        }
+    }
+    return null;
+}
+export async function readClipboardImage(platform = process.platform, env = process.env) {
+    if (platform === "darwin")
+        return macos();
+    if (platform === "linux")
+        return linux(env);
+    return null;
+}

package/dist/config.js

@@ -0,0 +1,40 @@
+// Where a login lives between runs: one JSON file, mode 0600, in the XDG config dir.
+//
+// It holds a REFRESH token (an offline one - see auth.ts), which is as good as a password for
+// this app until revoked, so the file is created private and re-chmodded on every write: an
+// existing file somebody loosened by hand is tightened again the next time a token rotates.
+import { mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+export function configPath(env = process.env) {
+    if (env.CUBES_CONFIG)
+        return env.CUBES_CONFIG;
+    const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "cubes", "config.json");
+}
+export function loadLogin(path = configPath()) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const v = JSON.parse(raw);
+        if (!v.host || !v.issuer || !v.clientId || !v.refreshToken || !v.endpoints?.token)
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveLogin(login, path = configPath()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(login, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function clearLogin(path = configPath()) {
+    rmSync(path, { force: true });
+}

package/dist/keys.js

@@ -0,0 +1,68 @@
+// What the CLI keeps for itself out of the keystroke stream. Everything else goes to the session
+// byte-for-byte, which is the whole point: your terminal's keybindings, your Option-as-Meta, your
+// Ctrl-C all reach `claude` exactly as they would locally.
+//
+// Two bytes are ours:
+//   • Ctrl-]  (0x1d) DETACH - the telnet/`docker attach` key, chosen because neither Claude Code nor
+//             tmux binds it, so taking it costs the session nothing.
+//   • Ctrl-V  (0x16) PASTE AN IMAGE - Claude Code's own image-paste key. Locally it reads the
+//             clipboard of the machine it runs on; here that is a pod with no clipboard, so the CLI
+//             reads YOURS, uploads it, and types the path (what the web terminal does on paste).
+//             With no image on the clipboard the 0x16 is sent through untouched.
+//
+// Neither is honoured inside a bracketed paste: pasted text is data, and a stray 0x1d in a paste
+// must not drop the connection.
+export const DETACH_BYTE = 0x1d;
+export const PASTE_IMAGE_BYTE = 0x16;
+const PASTE_START = [0x1b, 0x5b, 0x32, 0x30, 0x30, 0x7e]; // ESC [ 2 0 0 ~
+const PASTE_END = [0x1b, 0x5b, 0x32, 0x30, 0x31, 0x7e]; //   ESC [ 2 0 1 ~
+function matchAt(buf, i, seq) {
+    if (i + seq.length > buf.length)
+        return false;
+    for (let k = 0; k < seq.length; k++)
+        if (buf[i + k] !== seq[k])
+            return false;
+    return true;
+}
+export class InputFilter {
+    opts;
+    inPaste = false;
+    constructor(opts = { pasteImage: true }) {
+        this.opts = opts;
+    }
+    feed(chunk) {
+        const out = [];
+        let start = 0;
+        const flush = (end) => {
+            if (end > start)
+                out.push({ kind: "send", bytes: chunk.subarray(start, end) });
+        };
+        for (let i = 0; i < chunk.length; i++) {
+            if (chunk[i] === 0x1b && matchAt(chunk, i, PASTE_START)) {
+                this.inPaste = true;
+                i += PASTE_START.length - 1;
+                continue;
+            }
+            if (this.inPaste) {
+                if (chunk[i] === 0x1b && matchAt(chunk, i, PASTE_END)) {
+                    this.inPaste = false;
+                    i += PASTE_END.length - 1;
+                }
+                continue;
+            }
+            const b = chunk[i];
+            if (b === DETACH_BYTE) {
+                flush(i);
+                out.push({ kind: "detach" });
+                return out; // whatever was typed after the detach key is not the session's
+            }
+            if (b === PASTE_IMAGE_BYTE && this.opts.pasteImage) {
+                flush(i);
+                out.push({ kind: "paste-image" });
+                start = i + 1;
+            }
+        }
+        flush(chunk.length);
+        return out;
+    }
+}

package/dist/sessions.js

@@ -0,0 +1,83 @@
+// Listing sessions and turning what someone typed (an id, an id prefix, part of a title) into one.
+import { CliError } from "./auth.js";
+export const LIVE = new Set(["starting", "running"]);
+/** An editor row or a headless run has no terminal to attach to. */
+export function attachable(s) {
+    return s.origin !== "ide" && s.exec_mode !== "headless";
+}
+export async function listSessions(api, opts = {}) {
+    const q = new URLSearchParams({ limit: "200" });
+    if (opts.all)
+        q.set("scope", "all");
+    const page = await api.get(`/sessions?${q}`);
+    return (page.sessions ?? []).filter(attachable);
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(s) {
+    return UUID.test(s);
+}
+/** Pick ONE session out of `rows` for `query`, most specific match first. Ambiguity is an error that
+ *  names the candidates, never a guess: attaching takes the keyboard of whatever it lands on. */
+export function resolveSession(rows, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        throw new CliError("which session? pass an id or part of its title");
+    const tiers = [
+        (s) => s.id.toLowerCase() === q,
+        (s) => q.length >= 4 && s.id.toLowerCase().startsWith(q),
+        (s) => (s.title ?? "").toLowerCase() === q,
+        (s) => (s.title ?? "").toLowerCase().includes(q),
+    ];
+    for (const match of tiers) {
+        const hits = rows.filter(match);
+        if (hits.length === 1)
+            return hits[0];
+        if (hits.length > 1) {
+            // Several, but exactly one is live: that is almost always the one meant.
+            const live = hits.filter((s) => LIVE.has(s.status));
+            if (live.length === 1)
+                return live[0];
+            throw new CliError(`"${query}" matches ${hits.length} sessions:\n${formatTable(hits.slice(0, 10), 100)}\nuse more of the id`);
+        }
+    }
+    throw new CliError(`no session matches "${query}" - see \`cubes ls\``);
+}
+export function age(iso, now = Date.now()) {
+    if (!iso)
+        return "-";
+    const s = Math.max(0, Math.floor((now - Date.parse(iso)) / 1000));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    if (s < 86400)
+        return `${Math.floor(s / 3600)}h`;
+    return `${Math.floor(s / 86400)}d`;
+}
+export function stateOf(s) {
+    if (s.status === "running")
+        return s.activity_status || "running";
+    return s.status;
+}
+function cut(s, w) {
+    if (w <= 1)
+        return "";
+    return s.length <= w ? s : s.slice(0, w - 1) + "…";
+}
+export function formatTable(rows, width, now = Date.now()) {
+    const head = ["ID", "STATE", "AGE", "TITLE", "REPO"];
+    const body = rows.map((s) => [
+        s.id.slice(0, 8),
+        stateOf(s),
+        age(s.last_attached_at ?? s.created_at, now),
+        s.title || "(untitled)",
+        s.repo_full_name ?? "",
+    ]);
+    const w = (i) => Math.max(head[i].length, ...body.map((r) => r[i].length));
+    const fixed = [w(0), w(1), w(2)];
+    const repoW = Math.min(w(4), 32);
+    const titleW = Math.max(10, Math.min(w(3), width - fixed.reduce((a, b) => a + b, 0) - repoW - 8));
+    const line = (r) => [r[0].padEnd(fixed[0]), r[1].padEnd(fixed[1]), r[2].padStart(fixed[2]),
+        cut(r[3], titleW).padEnd(titleW), cut(r[4], repoW)].join("  ").trimEnd();
+    return [line(head), ...body.map(line)].join("\n");
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Attach to your Cubes sessions from your own terminal (Warp, iTerm, Ghostty, anything).",
+  "type": "module",
+  "bin": {
+    "cubes": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "cubes",
+    "claude",
+    "terminal",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "ws": "^8.18.0"
+  }
+}