@hellix-ai/cubes 0.1.1 → 0.1.3

package/README.md

@@ -7,12 +7,12 @@ Terminal.app, anything) with your own font, colors and keyboard shortcuts.
 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 ls                             # sessions, under a heading per group (--mine, --live)
 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>`.
+No install: `npx @hellix-ai/cubes attach <session>`. Later, `cubes upgrade` updates it in place.
 
 ## While attached
 
@@ -28,8 +28,9 @@ Every key goes to the session, exactly as if Claude Code were running locally, e
 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.
+A stopped or hibernated session is resumed before attaching (`--no-resume` to refuse), with the
+spinning Cubes mark on screen until it is up. 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.
@@ -41,10 +42,15 @@ cubes login [--host URL] [--org ALIAS] [--no-browser]
 cubes logout
 cubes whoami
 cubes org [ALIAS]
-cubes ls [--all] [--json]
+cubes ls [--mine] [--live] [--all] [--json]
 cubes attach [SESSION] [--view] [--no-resume]
+cubes upgrade [--check]
 ```
 
+`cubes ls` lists sessions the way the web's Sessions page does: a section per package, then per group
+(A-Z), then Ungrouped, live ones first in each. `--mine` keeps the ones you started, `--live` the ones
+running now; they combine. `--all` adds sessions other sessions spawned; `--json` prints the rows.
+
 `--org ALIAS` works on any command. If you belong to several organizations, `cubes org` lists them and
 `cubes org <alias>` changes the default.
 

package/dist/cli.js

@@ -11,9 +11,10 @@ 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 { CubeSpinner } from "./cube.js";
 import { clearLogin, configPath, loadLogin, saveLogin } from "./config.js";
 import { parseArgs } from "./args.js";
-import { formatTable, isUuid, listSessions, LIVE, resolveSession, stateOf } from "./sessions.js";
+import { formatSections, isUuid, listSessions, LIVE, resolveSession, sectionize, stateOf } from "./sessions.js";
 import { upgrade } from "./upgrade.js";
 const PKG = createRequire(import.meta.url)("../package.json");
 const VERSION = PKG.version;
@@ -24,7 +25,8 @@ Usage:
   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 ls [--mine] [--live] [--all] [--json]             list sessions by group (--mine: you started them,
+                                                          --live: running now, --all: include spawned ones)
   cubes attach [SESSION] [--view] [--no-resume]           attach to a session
   cubes upgrade [--check]                                 install the newest cubes (--check only reports)
 
@@ -93,8 +95,14 @@ async function cmdLogin(a) {
     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 spin = new CubeSpinner(process.stderr, "Waiting for you to approve it in the browser");
+    let tokens;
+    try {
+        tokens = await pollDevice(d, start);
+    }
+    finally {
+        spin.stop();
+    }
     const orgs = orgsOf(tokens.access_token);
     let org = str(a.flags, "org");
     if (org && orgs.length && !orgs.includes(org))
@@ -153,16 +161,21 @@ async function cmdOrg(a) {
 }
 async function cmdLs(a) {
     const api = makeApi(currentSession({ org: str(a.flags, "org") }));
-    const rows = await listSessions(api, { all: a.flags.has("all") });
+    const mine = a.flags.has("mine");
+    const live = a.flags.has("live");
+    // Both narrow, and they compose: `--mine --live` is "my sessions that are running now".
+    const rows = (await listSessions(api, { all: a.flags.has("all") }))
+        .filter((r) => (!mine || r.created_by_me === true) && (!live || LIVE.has(r.status)));
     if (a.flags.has("json")) {
         process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
         return;
     }
     if (!rows.length) {
-        process.stderr.write("No sessions.\n");
+        process.stderr.write(`No ${live ? "live " : ""}sessions${mine ? " of yours" : ""}.\n`);
         return;
     }
-    process.stdout.write(formatTable(rows, process.stdout.columns ?? 120) + "\n");
+    const color = !!process.stdout.isTTY && !process.env.NO_COLOR;
+    process.stdout.write(formatSections(sectionize(rows), process.stdout.columns ?? 120, { color }) + "\n");
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Bring a stopped/hibernated session back and wait until its terminal can be attached. */
@@ -171,36 +184,38 @@ async function ensureRunning(api, row, resume) {
     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`);
+    if (!LIVE.has(s.status) && !resume)
+        throw new CliError(`that session is ${s.status}; leave out --no-resume to bring it back`);
+    const name = `"${s.title ?? s.id.slice(0, 8)}"`;
+    // The same cube the session's own screen spins while Claude boots, so the wait reads as one thing.
+    const spin = new CubeSpinner(process.stderr, `${LIVE.has(s.status) ? "Starting" : "Resuming"} ${name}`);
+    try {
+        if (!LIVE.has(s.status)) {
+            try {
+                await api.post(`/sessions/${id}/resume`);
+            }
+            catch (e) {
+                if (!(e instanceof ApiError && e.status === 409 && /already running/.test(e.message)))
+                    throw e;
+            }
         }
-        catch (e) {
-            if (!(e instanceof ApiError && e.status === 409 && /already running/.test(e.message)))
-                throw e;
+        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})`);
+            if (s.provision_note) {
+                spin.update(`${s.provision_note}${s.provision_total ? ` (${s.provision_done ?? 0}/${s.provision_total})` : ""}`);
+            }
+            await sleep(1000);
         }
+        throw new CliError("the session is taking too long to start - check it in the browser");
     }
-    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);
+    finally {
+        spin.stop();
     }
-    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") });

package/dist/cube.js

@@ -0,0 +1,168 @@
+// The Cubes mark as a spinning ASCII cube, drawn in YOUR terminal while the CLI waits on something.
+//
+// It is the session boot animation (server/src/engine/interactiveAuth.ts, CUBE_SPIN_AWK) ported
+// line for line: the same six faces sampled parametrically, rotated yaw-then-pitch with the pitch on
+// the true isometric angle (so frame 0 is the app icon's pose), the same back-face culling, the same
+// Lambert shading quantised to five steps of one indigo ramp and four ASCII densities, and the same
+// 2π/40 turn so it loops without a stutter. So a resume looks like one continuous thing: this cube
+// while the session comes back, then the session's own cube while Claude boots, then Claude.
+//
+// It is drawn INLINE, not on the alternate screen: what is above it (a sign-in code you have to type)
+// stays where it is, and when the wait ends the region is erased and the cursor is back where it was.
+const NFR = 40;
+const CH = ["", "+", "*", "*", "%", "#"];
+const CO = ["", "\x1b[38;5;61m", "\x1b[38;5;62m", "\x1b[38;5;63m", "\x1b[38;5;105m", "\x1b[38;5;147m"];
+const CAPTION = "\x1b[38;5;147m";
+const FACES = [
+    // outward normal, then the two tangents that sweep it
+    { n: [0, 1, 0], a: [1, 0, 0], b: [0, 0, 1] },
+    { n: [0, -1, 0], a: [1, 0, 0], b: [0, 0, 1] },
+    { n: [1, 0, 0], a: [0, 1, 0], b: [0, 0, 1] },
+    { n: [-1, 0, 0], a: [0, 1, 0], b: [0, 0, 1] },
+    { n: [0, 0, 1], a: [1, 0, 0], b: [0, 1, 0] },
+    { n: [0, 0, -1], a: [1, 0, 0], b: [0, 1, 0] },
+];
+const SP = Math.sin(0.61548);
+const CP = Math.cos(0.61548);
+const L = [-0.5, 0.72, 0.48];
+/** The cube's size for a terminal of `cols` x `rows`: the boot window's caps, a little shorter so
+ *  an inline cube does not take over the screen. Null when there is no room to draw one. */
+export function cubeSize(cols, rows) {
+    let w = Math.min(cols - 4, 46);
+    let h = Math.min(rows - 6, 15);
+    if (h % 2 === 0)
+        h--;
+    if (w < 30 || h < 9)
+        return null;
+    return { w, h };
+}
+/** One frame: `h` rows of shade levels 0-5 (0 = empty). Frame numbers past 39 wrap seamlessly. */
+export function cubeFrame(frame, w, h) {
+    const cx = (w - 1) / 2;
+    const cy = (h - 1) / 2;
+    const ys = cy / 1.634;
+    const xs = Math.min(2 * ys, cx / 1.415);
+    const th = 0.785398 + frame * (6.283185 / NFR);
+    const sq = Math.sin(th);
+    const cq = Math.cos(th);
+    const sc = Array.from({ length: h }, () => new Array(w).fill(0));
+    for (const f of FACES) {
+        const [nx, ny, nz] = f.n;
+        const mx = nx * cq - nz * sq;
+        const mz = nx * sq + nz * cq;
+        const qy = ny * CP - mz * SP;
+        const qz = ny * SP + mz * CP;
+        if (qz <= 0.001)
+            continue; // facing away
+        const bb = mx * L[0] + qy * L[1] + qz * L[2];
+        const lv = Math.min(5, Math.max(1, 1 + Math.floor(((bb + 0.55) / 1.5) * 5)));
+        for (let u = -1; u <= 1.0001; u += 0.035) {
+            for (let v = -1; v <= 1.0001; v += 0.035) {
+                const px = nx + u * f.a[0] + v * f.b[0];
+                const py = ny + u * f.a[1] + v * f.b[1];
+                const pz = nz + u * f.a[2] + v * f.b[2];
+                const rx = px * cq - pz * sq;
+                const rz = px * sq + pz * cq;
+                const ty = py * CP - rz * SP;
+                const sx = Math.floor(cx + xs * rx + 0.5);
+                const sy = Math.floor(cy - ys * ty + 0.5);
+                if (sx < 0 || sx >= w || sy < 0 || sy >= h)
+                    continue;
+                sc[sy][sx] = lv;
+            }
+        }
+    }
+    return sc;
+}
+export function renderRow(levels, color) {
+    let out = "";
+    let cur = 0;
+    for (const s of levels) {
+        if (s === 0) {
+            if (cur && color)
+                out += "\x1b[0m";
+            cur = 0;
+            out += " ";
+        }
+        else {
+            if (cur !== s && color)
+                out += CO[s];
+            cur = s;
+            out += CH[s];
+        }
+    }
+    return (color ? out + "\x1b[0m" : out).replace(/\s+$/, "");
+}
+/**
+ * A wait with the cube on it. Where it cannot draw (not a terminal, TERM=dumb, or too small), each
+ * caption is printed as an ordinary line instead, so a pipe or a CI log still says what is happening.
+ * NO_COLOR keeps the cube and drops the colour, which the four ASCII densities survive.
+ */
+export class CubeSpinner {
+    out;
+    timer = null;
+    frame = 0;
+    drawn = 0;
+    caption;
+    size;
+    color;
+    restore = () => this.out.write("\x1b[?25h");
+    // A Ctrl-C mid-wait: Node's default SIGINT exit runs no "exit" listeners, so it would leave the
+    // cube on screen and the cursor hidden. Clean up, then exit the way the default would have.
+    onSigint = () => { this.stop(); process.exit(130); };
+    constructor(out, caption, env = process.env) {
+        this.out = out;
+        this.caption = caption;
+        this.size = out.isTTY && env.TERM !== "dumb" ? cubeSize(out.columns ?? 80, out.rows ?? 24) : null;
+        this.color = !env.NO_COLOR;
+        if (!this.size) {
+            out.write(`${caption}…\n`);
+            return;
+        }
+        out.write("\x1b[?25l");
+        process.once("exit", this.restore);
+        process.once("SIGINT", this.onSigint);
+        this.draw();
+        this.timer = setInterval(() => this.draw(), 60);
+    }
+    update(caption) {
+        if (caption === this.caption)
+            return;
+        this.caption = caption;
+        if (!this.size)
+            this.out.write(`${caption}…\n`);
+    }
+    /** Erase the cube, put the cursor back, and say how it ended (if anything). */
+    stop(final) {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (this.size) {
+            if (this.drawn)
+                this.out.write(`\x1b[${this.drawn}A\r\x1b[J`);
+            this.restore();
+            process.removeListener("exit", this.restore);
+            process.removeListener("SIGINT", this.onSigint);
+            this.size = null;
+        }
+        if (final)
+            this.out.write(`${final}\n`);
+    }
+    draw() {
+        const { w, h } = this.size;
+        const rows = cubeFrame(this.frame, w, h);
+        const dots = ".".repeat((Math.floor(this.frame / 4) % 3) + 1);
+        // A caption that wraps would add a row this redraw does not know to move back over.
+        const room = Math.max(10, (this.out.columns ?? 80) - 6);
+        const text = this.caption.length > room ? this.caption.slice(0, room - 1) + "…" : this.caption;
+        const pad = " ".repeat(Math.max(0, Math.floor((w - text.length - 3) / 2) + 2));
+        let s = this.drawn ? `\x1b[${this.drawn}A` : "";
+        for (const r of rows)
+            s += `\r  ${renderRow(r, this.color)}\x1b[K\n`;
+        const cap = `${text}${dots}`;
+        s += `\r\x1b[K\n\r${pad}${this.color ? CAPTION + cap + "\x1b[0m" : cap}\x1b[K\n`;
+        this.out.write(s);
+        this.drawn = rows.length + 2;
+        this.frame = (this.frame + 1) % NFR;
+    }
+}

package/dist/sessions.js

@@ -64,20 +64,85 @@ function cut(s, w) {
         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", "GROUP"];
-    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.group_name ?? "",
-    ]);
+/** Column layout shared by every table: widths come from ALL the rows, so the sections of one listing
+ *  line up with each other. */
+function layout(rows, width, now) {
+    const head = ["ID", "STATE", "AGE", "TITLE"];
+    const cells = (s) => [s.id.slice(0, 8), stateOf(s), age(s.last_attached_at ?? s.created_at, now), s.title || "(untitled)"];
+    const body = rows.map(cells);
     const w = (i) => Math.max(head[i].length, ...body.map((r) => r[i].length));
     const fixed = [w(0), w(1), w(2)];
-    const groupW = Math.min(w(4), 32);
-    const titleW = Math.max(10, Math.min(w(3), width - fixed.reduce((a, b) => a + b, 0) - groupW - 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], groupW)].join("  ").trimEnd();
-    return [line(head), ...body.map(line)].join("\n");
+    const titleW = Math.max(10, Math.min(w(3), width - fixed.reduce((a, b) => a + b, 0) - 6));
+    const line = (r) => [r[0].padEnd(fixed[0]), r[1].padEnd(fixed[1]), r[2].padStart(fixed[2]), cut(r[3], titleW)].join("  ").trimEnd();
+    return { header: line(head), row: (s) => line(cells(s)), width: fixed.reduce((a, b) => a + b, 0) + titleW + 6 };
+}
+export function formatTable(rows, width, now = Date.now()) {
+    const l = layout(rows, width, now);
+    return [l.header, ...rows.map(l.row)].join("\n");
+}
+/**
+ * The web Sessions page's sections (web SessionsPage.tsx groupSections), so a listing reads the same in
+ * both places: one per PACKAGE (most recently started first), then one per GROUP A-Z, then Ungrouped.
+ * Inside each, live sessions first, then the most recently started. Unlike the page, an empty group is
+ * not shown - there is nothing to do with an empty heading in a terminal.
+ */
+export function sectionize(rows) {
+    const startOf = (r) => (r ? r.started_at ?? r.ended_at ?? r.created_at ?? "" : "");
+    const order = (a, b) => {
+        const la = LIVE.has(a.status);
+        const lb = LIVE.has(b.status);
+        if (la !== lb)
+            return la ? -1 : 1;
+        return startOf(b).localeCompare(startOf(a));
+    };
+    const pkgs = new Map();
+    const groups = new Map();
+    const ungrouped = [];
+    for (const r of rows) {
+        if (r.package_id) {
+            const sec = pkgs.get(r.package_id) ?? { title: r.package_name || "Package", rows: [] };
+            sec.rows.push(r);
+            pkgs.set(r.package_id, sec);
+        }
+        else if (r.group_id && r.group_name) {
+            const sec = groups.get(r.group_id) ?? { title: r.group_name, rows: [] };
+            sec.rows.push(r);
+            groups.set(r.group_id, sec);
+        }
+        else {
+            ungrouped.push(r);
+        }
+    }
+    for (const sec of [...pkgs.values(), ...groups.values()])
+        sec.rows.sort(order);
+    const out = [
+        ...[...pkgs.values()].sort((a, b) => startOf(b.rows[0]).localeCompare(startOf(a.rows[0]))),
+        ...[...groups.values()].sort((a, b) => a.title.localeCompare(b.title)),
+    ];
+    if (ungrouped.length)
+        out.push({ title: "Ungrouped", rows: ungrouped.sort(order) });
+    return out;
+}
+/** The listing: one column header, then each section under a rule naming it and its count. A listing
+ *  that is ALL ungrouped (an org that does not use groups) gets no rule at all - it would only say so. */
+export function formatSections(sections, width, opts = {}) {
+    const all = sections.flatMap((s) => s.rows);
+    const l = layout(all, width, opts.now ?? Date.now());
+    const dim = (t) => (opts.color ? `\x1b[2m${t}\x1b[0m` : t);
+    const bold = (t) => (opts.color ? `\x1b[1m${t}\x1b[0m` : t);
+    const ruleW = Math.max(24, Math.min(width, l.width));
+    const out = [dim(l.header)];
+    const bare = sections.length === 1 && sections[0].title === "Ungrouped";
+    sections.forEach((sec, i) => {
+        if (!bare) {
+            const label = `${sec.title} (${sec.rows.length})`;
+            const fill = Math.max(2, ruleW - label.length - 4);
+            if (i > 0)
+                out.push("");
+            out.push(`${dim("──")} ${bold(sec.title)} ${dim(`(${sec.rows.length}) ${"─".repeat(fill)}`)}`);
+        }
+        for (const r of sec.rows)
+            out.push(l.row(r));
+    });
+    return out.join("\n");
 }

package/package.json

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