@hellix-ai/cubes 0.1.0 → 0.1.2

package/README.md

@@ -12,7 +12,7 @@ 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.
@@ -43,6 +44,7 @@ cubes whoami
 cubes org [ALIAS]
 cubes ls [--all] [--json]
 cubes attach [SESSION] [--view] [--no-resume]
+cubes upgrade [--check]
 ```
 
 `--org ALIAS` works on any command. If you belong to several organizations, `cubes org` lists them and

package/dist/cli.js

@@ -11,10 +11,13 @@ 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";
-const VERSION = createRequire(import.meta.url)("../package.json").version;
+import { upgrade } from "./upgrade.js";
+const PKG = createRequire(import.meta.url)("../package.json");
+const VERSION = PKG.version;
 const HELP = `cubes ${VERSION} - attach to your Cubes sessions from your own terminal
 
 Usage:
@@ -24,6 +27,7 @@ Usage:
   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
+  cubes upgrade [--check]                                 install the newest cubes (--check only reports)
 
 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.
@@ -90,8 +94,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))
@@ -168,36 +178,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") });
@@ -281,10 +293,26 @@ async function main(argv) {
             return 0;
         case "attach":
         case "a": return cmdAttach(a);
+        case "upgrade":
+        case "update":
+            return upgrade({
+                pkg: PKG.name, current: VERSION, scriptPath: process.argv[1] ?? "",
+                log: (line) => process.stderr.write(`${line}\n`),
+            }, { check: a.flags.has("check") });
         default: throw new CliError(`unknown command "${a.cmd}" - see \`cubes help\``);
     }
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+/** Exit only once everything written has reached its destination. A write to a PIPE is asynchronous
+ *  in Node, so a bare process.exit() after `cubes ls --json | jq` cut the JSON off mid-string. An empty
+ *  write's callback fires after every write queued before it. */
+function exitAfterFlush(code) {
+    let pending = 2;
+    const done = () => { if (--pending === 0)
+        process.exit(code); };
+    process.stdout.write("", done);
+    process.stderr.write("", done);
+}
+main(process.argv.slice(2)).then((code) => exitAfterFlush(code), (e) => {
     process.stderr.write(`cubes: ${e instanceof Error ? e.message : String(e)}\n`);
-    process.exit(e instanceof CliError ? e.exitCode : 1);
+    exitAfterFlush(e instanceof CliError ? e.exitCode : 1);
 });

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

@@ -65,19 +65,19 @@ function cut(s, w) {
     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 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.repo_full_name ?? "",
+        s.group_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 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], repoW)].join("  ").trimEnd();
+        cut(r[3], titleW).padEnd(titleW), cut(r[4], groupW)].join("  ").trimEnd();
     return [line(head), ...body.map(line)].join("\n");
 }

package/dist/upgrade.js

@@ -0,0 +1,105 @@
+// `cubes upgrade`: ask npm for the newest release and reinstall with whatever installed this copy.
+//
+// The install command has to match how the CLI got onto the machine: `npm install -g` over a pnpm or
+// bun global install leaves the old copy first on PATH, and an npx run is a throwaway cache entry
+// that `npx @hellix-ai/cubes@latest` already refreshes. The path of the running script says which.
+import { spawn } from "node:child_process";
+import { CliError } from "./auth.js";
+export const REGISTRY = "https://registry.npmjs.org";
+/** -1 / 0 / 1 for plain x.y.z versions. A prerelease sorts below its release (0.2.0-rc < 0.2.0). */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core = "", pre] = v.trim().replace(/^v/, "").split("-", 2);
+        return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+        if (d)
+            return d > 0 ? 1 : -1;
+    }
+    if (x.pre && !y.pre)
+        return -1;
+    if (!x.pre && y.pre)
+        return 1;
+    return 0;
+}
+export function installerFor(scriptPath) {
+    const p = scriptPath.replace(/\\/g, "/");
+    if (p.includes("/_npx/"))
+        return "npx";
+    if (p.includes("/.bun/"))
+        return "bun";
+    if (/\/pnpm\/|\/\.pnpm\//.test(p))
+        return "pnpm";
+    if (/\/yarn\/global\//.test(p))
+        return "yarn";
+    return "npm";
+}
+export function installCommand(installer, spec) {
+    switch (installer) {
+        case "pnpm": return ["pnpm", "add", "-g", spec];
+        case "bun": return ["bun", "add", "-g", spec];
+        case "yarn": return ["yarn", "global", "add", spec];
+        default: return ["npm", "install", "-g", spec];
+    }
+}
+export async function latestVersion(pkg, fetchImpl = fetch) {
+    let res;
+    try {
+        res = await fetchImpl(`${REGISTRY}/${pkg.replace("/", "%2f")}/latest`, { signal: AbortSignal.timeout(10_000) });
+    }
+    catch (e) {
+        throw new CliError(`cannot reach the npm registry: ${e.message}`);
+    }
+    if (!res.ok)
+        throw new CliError(`the npm registry answered HTTP ${res.status} for ${pkg}`);
+    const body = (await res.json());
+    if (typeof body.version !== "string")
+        throw new CliError("the npm registry did not say what the latest version is");
+    return body.version;
+}
+function runInherited(argv) {
+    return new Promise((resolve) => {
+        // shell on Windows only, where the package managers are .cmd shims spawn cannot start directly.
+        const child = spawn(argv[0], argv.slice(1), { stdio: "inherit", shell: process.platform === "win32" });
+        child.on("error", () => resolve(127));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+/** Returns the process exit code. `check` only reports. */
+export async function upgrade(d, opts = {}) {
+    const latest = await latestVersion(d.pkg, d.fetchImpl);
+    const cmp = compareVersions(d.current, latest);
+    if (cmp === 0) {
+        d.log(`cubes ${d.current} is the latest version.`);
+        return 0;
+    }
+    if (cmp > 0) {
+        d.log(`cubes ${d.current} is newer than the latest published (${latest}); nothing to do.`);
+        return 0;
+    }
+    const installer = installerFor(d.scriptPath);
+    const spec = `${d.pkg}@${latest}`;
+    if (installer === "npx") {
+        d.log(`cubes ${latest} is available (this is ${d.current}). You are running it through npx, so ask for the new one:`);
+        d.log(`  npx ${d.pkg}@latest <command>`);
+        return 0;
+    }
+    const argv = installCommand(installer, spec);
+    if (opts.check) {
+        d.log(`cubes ${latest} is available (you have ${d.current}). Run \`cubes upgrade\`, or: ${argv.join(" ")}`);
+        return 0;
+    }
+    d.log(`Upgrading cubes ${d.current} -> ${latest}: ${argv.join(" ")}`);
+    const code = await (d.run ?? runInherited)(argv);
+    if (code === 127)
+        throw new CliError(`could not run \`${argv[0]}\` - upgrade by hand: ${argv.join(" ")}`);
+    if (code !== 0) {
+        throw new CliError(`the upgrade failed (exit ${code}). If it was a permissions error, your global ${argv[0]} ` +
+            `directory is not writable by you - run it with the rights it needs: ${argv.join(" ")}`);
+    }
+    d.log(`cubes is now ${latest}.`);
+    return 0;
+}

package/package.json

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