@hellix-ai/cubes 0.2.1 → 0.3.0

package/dist/prompt.js

@@ -0,0 +1,117 @@
+// Asking questions in a terminal: line-based, numbered, Enter takes the default.
+//
+// Deliberately not a full-screen picker. The session form runs before anything is attached, in
+// whatever terminal the person has (Warp, a plain ssh, a CI log when piped), and a numbered list read
+// with one line of input works in every one of them. Questions go to stderr so stdout stays clean.
+//
+// Behind an interface so the form can be driven by a script in tests.
+import { createInterface } from "node:readline/promises";
+import { CliError } from "./auth.js";
+/** "1 3", "1,3", "2-4", "1, 3-5" -> zero-based indexes, or null when it does not parse. */
+export function parseNumbers(answer, count) {
+    const out = new Set();
+    for (const part of answer.split(/[\s,]+/).filter(Boolean)) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(part);
+        if (!m)
+            return null;
+        const a = Number(m[1]);
+        const b = m[2] ? Number(m[2]) : a;
+        if (a < 1 || b > count || a > b)
+            return null;
+        for (let i = a; i <= b; i++)
+            out.add(i - 1);
+    }
+    return [...out].sort((x, y) => x - y);
+}
+export function terminalPrompter(input = process.stdin, output = process.stderr, color = !process.env.NO_COLOR && !!output.isTTY) {
+    const dim = (t) => (color ? `\x1b[2m${t}\x1b[0m` : t);
+    const bold = (t) => (color ? `\x1b[1m${t}\x1b[0m` : t);
+    const ask = async (q) => {
+        const rl = createInterface({ input, output, terminal: input.isTTY ?? false });
+        // Ctrl-C at a question leaves the whole command, not just the question.
+        rl.on("SIGINT", () => { rl.close(); output.write("\n"); process.exit(130); });
+        try {
+            return (await rl.question(q)).trim();
+        }
+        catch (e) {
+            // Ctrl-D (end of input) at a question: nothing more is coming, so stop here, plainly.
+            if (e.code === "ABORT_ERR")
+                throw new CliError("cancelled - nothing was started");
+            throw e;
+        }
+        finally {
+            rl.close();
+        }
+    };
+    const list = (choices, marked) => {
+        const w = String(choices.length).length;
+        choices.forEach((c, i) => {
+            const mark = marked(i) ? "*" : " ";
+            output.write(`  ${mark} ${String(i + 1).padStart(w)}) ${c.label}${c.hint ? `  ${dim(c.hint)}` : ""}\n`);
+        });
+    };
+    return {
+        async text(question, def) {
+            const a = await ask(`${bold(question)}${def ? ` ${dim(`[${def}]`)}` : ""}: `);
+            return a || def || "";
+        },
+        async confirm(question, def) {
+            for (;;) {
+                const a = (await ask(`${bold(question)} ${dim(def ? "[Y/n]" : "[y/N]")} `)).toLowerCase();
+                if (!a)
+                    return def;
+                if (a === "y" || a === "yes")
+                    return true;
+                if (a === "n" || a === "no")
+                    return false;
+            }
+        },
+        async select(question, choices, def = 0) {
+            if (!choices.length)
+                throw new CliError(`nothing to choose from for "${question}"`);
+            output.write(`${bold(question)}\n`);
+            list(choices, (i) => i === def);
+            for (;;) {
+                const a = await ask(`  ${dim(`number, Enter for ${def + 1}`)}: `);
+                if (!a)
+                    return choices[def].value;
+                const n = Number(a);
+                if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+                    return choices[n - 1].value;
+                output.write(`  ${dim(`pick 1-${choices.length}`)}\n`);
+            }
+        },
+        async multi(question, choices, defs) {
+            output.write(`${bold(question)}\n`);
+            list(choices, (i) => defs.includes(i));
+            for (;;) {
+                const a = await ask(`  ${dim(`numbers like "1 3" or "2-4", - for none, Enter keeps ${defs.length ? "the * ones" : "none"}`)}: `);
+                if (!a)
+                    return defs.map((i) => choices[i].value);
+                if (a === "-")
+                    return [];
+                const picked = parseNumbers(a, choices.length);
+                if (picked)
+                    return picked.map((i) => choices[i].value);
+                output.write(`  ${dim(`numbers between 1 and ${choices.length}`)}\n`);
+            }
+        },
+        note(line) {
+            output.write(`${dim(line)}\n`);
+        },
+    };
+}
+/** For `--yes` and for scripts: every question takes its default, and says so. */
+export function defaultsPrompter(output = process.stderr) {
+    return {
+        text: async (_q, def) => def ?? "",
+        confirm: async (_q, def) => def,
+        select: async (q, choices, def = 0) => {
+            if (!choices.length)
+                throw new CliError(`nothing to choose from for "${q}"`);
+            return choices[def].value;
+        },
+        multi: async (_q, choices, defs) => defs.map((i) => choices[i].value),
+        note: (line) => { output.write(`${line}\n`); },
+    };
+}

package/dist/transfer.js

@@ -0,0 +1,166 @@
+// Moving a conversation between this computer and Cubes - the bytes half of `cubes import` and
+// `cubes export`. No prompts and no printing here: progress is a callback, failures are thrown.
+//
+// UP: the server takes a conversation in windows (`chunkBytes`, which it states - Cloudflare refuses a
+// request body over 100 MiB, and conversations are routinely bigger), each at an exact offset, so a
+// window whose response was lost is simply sent again and a window the server did not expect is
+// answered with where it actually is. The file is checksummed first and the server verifies it once the
+// last byte lands.
+//
+// DOWN: one streamed GET with an exact Content-Length. It is written next to its destination and only
+// renamed into place once every byte has arrived, so an interrupted export never leaves half a
+// conversation where `claude --resume` would find it.
+import { createHash, randomBytes } from "node:crypto";
+import { open, rm, stat, truncate } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { ApiError } from "./api.js";
+import { CliError } from "./auth.js";
+import { isConversationId } from "./local.js";
+const WINDOW = 1024 * 1024;
+/**
+ * How much of a conversation is WHOLE LINES right now. A conversation Claude Code is still writing on
+ * this computer can end mid-line; the upload stops at the last newline, and the bytes before it never
+ * change (the file is only ever appended to), so the checksum taken first still holds at the end.
+ */
+export async function wholeLinesLength(path) {
+    const size = (await stat(path)).size;
+    const fh = await open(path, "r");
+    try {
+        const buf = Buffer.alloc(WINDOW);
+        for (let end = size; end > 0;) {
+            const from = Math.max(0, end - WINDOW);
+            const { bytesRead } = await fh.read(buf, 0, end - from, from);
+            const nl = buf.subarray(0, bytesRead).lastIndexOf(0x0a);
+            if (nl >= 0)
+                return from + nl + 1;
+            end = from;
+        }
+        return 0;
+    }
+    finally {
+        await fh.close().catch(() => { });
+    }
+}
+export async function sha256Of(path, len) {
+    const h = createHash("sha256");
+    const fh = await open(path, "r");
+    try {
+        const buf = Buffer.alloc(4 * WINDOW);
+        for (let at = 0; at < len;) {
+            const { bytesRead } = await fh.read(buf, 0, Math.min(buf.length, len - at), at);
+            if (!bytesRead)
+                throw new CliError(`${path} got shorter while it was being read`);
+            h.update(buf.subarray(0, bytesRead));
+            at += bytesRead;
+        }
+    }
+    finally {
+        await fh.close().catch(() => { });
+    }
+    return h.digest("hex");
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Upload one conversation file and return the import id POST /api/sessions takes. */
+export async function uploadConversation(api, conv, onProgress = () => { }, opts = {}) {
+    const bytes = await wholeLinesLength(conv.path);
+    if (!bytes)
+        throw new CliError(`${conv.path} has no complete line in it - there is nothing to import`);
+    const sha256 = await sha256Of(conv.path, bytes);
+    const begin = await api.post("/session-imports", {
+        conversationId: conv.id, bytes, sha256, sourceCwd: conv.cwd,
+    });
+    const id = begin.id;
+    const chunk = Math.max(1, begin.chunkBytes);
+    const retries = opts.retries ?? 4;
+    const fh = await open(conv.path, "r");
+    try {
+        let at = 0;
+        onProgress(0, bytes);
+        while (at < bytes) {
+            const n = Math.min(chunk, bytes - at);
+            const buf = Buffer.alloc(n);
+            const { bytesRead } = await fh.read(buf, 0, n, at);
+            if (bytesRead !== n)
+                throw new CliError(`${conv.path} got shorter while it was being uploaded`);
+            for (let attempt = 0;; attempt++) {
+                try {
+                    const v = await api.put(`/session-imports/${encodeURIComponent(id)}/content?offset=${at}`, undefined, { raw: buf });
+                    at = v.received;
+                    break;
+                }
+                catch (e) {
+                    // The server is somewhere else than we thought (a retried window it had already taken, or
+                    // one it lost): carry on from where IT is.
+                    const received = e instanceof ApiError && e.status === 409
+                        ? e.body?.received : undefined;
+                    if (typeof received === "number") {
+                        at = received;
+                        break;
+                    }
+                    // Only a network failure or a server error is worth repeating; a refusal is final.
+                    const transient = !(e instanceof ApiError) || e.status >= 500;
+                    if (!transient || attempt >= retries)
+                        throw e;
+                    await sleep((opts.retryDelayMs ?? 1000) * (attempt + 1));
+                }
+            }
+            onProgress(at, bytes);
+        }
+        return { importId: id, bytes };
+    }
+    catch (e) {
+        await api.del(`/session-imports/${encodeURIComponent(id)}`).catch(() => undefined);
+        throw e;
+    }
+    finally {
+        await fh.close().catch(() => { });
+    }
+}
+/**
+ * Download a session's conversation. `targetFor` names where it will end up once its id is known (the
+ * server says it in a header), so the temporary file is written in the same directory.
+ */
+export async function downloadConversation(api, sessionId, targetFor, onProgress = () => { }) {
+    const res = await api.stream(`/sessions/${encodeURIComponent(sessionId)}/conversation`);
+    const conversationId = res.headers.get("x-conversation-id") ?? "";
+    if (!isConversationId(conversationId)) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new CliError("the server did not say which conversation this is - is it older than this CLI?");
+    }
+    const total = Number(res.headers.get("content-length"));
+    const target = targetFor(conversationId);
+    await mkdir(dirname(target), { recursive: true });
+    const part = join(dirname(target), `.${conversationId}.cubes-export-${randomBytes(4).toString("hex")}.part`);
+    const fh = await open(part, "w", 0o600);
+    let got = 0;
+    try {
+        if (!res.body)
+            throw new CliError("the server sent no conversation");
+        onProgress(0, total);
+        for await (const piece of res.body) {
+            await fh.write(piece);
+            got += piece.length;
+            onProgress(got, total);
+        }
+    }
+    catch (e) {
+        await fh.close().catch(() => { });
+        await rm(part, { force: true });
+        throw e instanceof CliError ? e : new CliError(`the download was cut off after ${got} bytes: ${e.message}`);
+    }
+    await fh.close();
+    if (Number.isFinite(total) && got !== total) {
+        await rm(part, { force: true });
+        throw new CliError(`the download was cut off: ${got} of ${total} bytes arrived - nothing was written, try again`);
+    }
+    // The session may have been halfway through writing its last line when the snapshot was taken.
+    const whole = await wholeLinesLength(part);
+    if (whole !== got)
+        await truncate(part, whole);
+    if (!whole) {
+        await rm(part, { force: true });
+        throw new CliError("that session's conversation has no complete line in it yet");
+    }
+    return { conversationId, file: part, bytes: whole };
+}

package/dist/tui/launch.js

@@ -13,8 +13,8 @@ const OPTIONS = [
     ["mouse", "on"],
     ["status", "off"],
     // ⚠ NO PREFIX. tmux's Ctrl-B is Claude Code's "run in background", and the session's own tmux (the
-    // one in the pod) has none either, so nothing here may eat a keystroke. Focus moves by mouse, by
-    // Ctrl-] from the session pane, and by Enter/Tab from the list.
+    // one in the pod) has none either, so nothing here may eat a keystroke Claude Code uses. Focus moves
+    // by mouse, by the SWITCH key below, and by Tab / a second Enter from the list.
     ["prefix", "None"],
     ["prefix2", "None"],
     // Escape must reach Claude Code at once: tmux's default 500 ms makes every Esc feel broken.
@@ -32,13 +32,29 @@ const OPTIONS = [
     ["visual-bell", "off"],
     ["allow-passthrough", "on"],
 ];
+/**
+ * The key that moves focus between the list and the session, from either side. Bound in tmux's root
+ * table so it works whatever the pane is doing (attached, resuming, showing "Disconnected").
+ *
+ * ⚠ It never reaches the session, so it must be a key Claude Code does not use - and it uses every
+ * plain key (Esc interrupts, Tab, Shift-Tab, the arrows, Enter, any character a prompt can hold) and
+ * most Ctrl ones, Ctrl-] included ("open artifact", 2.1.x; checked against its default keybindings).
+ * F1 is the one single key left: Claude Code binds no function key. On a MacBook the top row sends F1
+ * with fn held, unless "Use F1, F2, etc. keys as standard function keys" is on.
+ */
+const SWITCH_KEYS = ["F1"];
+function bindKeys() {
+    // `:.+` is the other pane: there are exactly two.
+    for (const key of SWITCH_KEYS)
+        tmux(["bind-key", "-n", key, "select-pane", "-t", ":.+"]);
+}
 function attachClient() {
     const env = { ...process.env };
     delete env.TMUX; // inside the person's own tmux: nest on purpose rather than refuse
     const r = spawnSync("tmux", ["-L", SOCKET, "attach-session", "-t", SESSION], { stdio: "inherit", env });
     return r.status ?? 0;
 }
-function build(org) {
+function build(org, version) {
     const cols = process.stdout.columns ?? 160;
     const rows = process.stdout.rows ?? 48;
     const env = org ? ["-e", `CUBES_ORG=${org}`] : [];
@@ -49,6 +65,7 @@ function build(org) {
     const left = created.out;
     for (const [k, v] of OPTIONS)
         tmux(["set-option", "-g", "-q", k, v]);
+    bindKeys();
     // ⚠ The same fix the session's own tmux carries (server Tmux.clientDefaults): without `ech`, tmux
     // draws gaps as real spaces. Warp left stale letters in every gap drawn with ECH. A SERVER option,
     // read when a client attaches, so it is set before ours does.
@@ -62,6 +79,7 @@ function build(org) {
         throw new CliError(`could not split the window: ${right.err || right.code}`);
     tmux(["set-option", "-t", SESSION, "@cubes_left", left]);
     tmux(["set-option", "-t", SESSION, "@cubes_right", right.out]);
+    tmux(["set-option", "-t", SESSION, "@cubes_version", version]);
     tmux(["select-pane", "-t", left]);
 }
 /**
@@ -78,6 +96,21 @@ function heal() {
         tmux(["respawn-pane", "-k", "-t", id, selfCommand(id === left ? ["_list"] : ["_pane"])]);
     }
 }
+/**
+ * A layout an older cubes built keeps running that version's list (the tmux outlives an upgrade), so
+ * bring it up to date: settings and keys, and a fresh list. The session pane is left alone - restarting
+ * it would reconnect, and resume a session that has ended - and runs the new code from the next open.
+ */
+function upgradeLayout(version) {
+    for (const [k, v] of OPTIONS)
+        tmux(["set-option", "-g", "-q", k, v]);
+    bindKeys();
+    tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]);
+    const left = tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_left"]).out;
+    if (left)
+        tmux(["respawn-pane", "-k", "-t", left, selfCommand(["_list"])]);
+    tmux(["set-option", "-t", SESSION, "@cubes_version", version]);
+}
 export async function launchTui(opts) {
     const v = tmuxVersion();
     if (v === null) {
@@ -90,9 +123,10 @@ export async function launchTui(opts) {
     await currentSession({ org: opts.org }).token();
     if (tmux(["has-session", "-t", SESSION]).code === 0) {
         heal();
-        tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]); // a layout built by an older cubes
+        if (tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_version"]).out !== opts.version)
+            upgradeLayout(opts.version);
     }
     else
-        build(opts.org);
+        build(opts.org, opts.version);
     return attachClient();
 }

package/dist/tui/listApp.js

@@ -1,5 +1,9 @@
 // The left pane of the split view: every session, grouped and nested, with its state, filterable,
 // and one keystroke (or click) from being open on the right.
+//
+// Opening SHOWS the session and leaves the keyboard here, so you can keep browsing: Enter on the next
+// one shows that instead. Going into the session is its own step - Tab, F1, or Enter again on the one
+// already showing.
 import { makeApi } from "../api.js";
 import { currentSession } from "../auth.js";
 import { age, listSessions, LIVE } from "../sessions.js";
@@ -12,7 +16,7 @@ const ACCENT = 62;
 /** As many WHOLE key hints as fit, in order of how much they are needed - never one cut in half -
  *  and the way out always last. */
 export function hints(width) {
-    const all = ["⏎ open", "l live", "m mine", "/ find", "^] back here", "←→ fold", "r refresh"];
+    const all = ["⏎ show", "F1 switch", "l live", "m mine", "/ find", "←→ fold", "r refresh"];
     const quit = "q quit";
     let out = "";
     for (const h of all) {
@@ -141,7 +145,17 @@ export async function runList() {
         const next = list[Math.max(0, Math.min(list.length - 1, at + delta))];
         st.selectedId = next.row.id;
     };
+    const goIn = () => {
+        const right = getSessionOption("@cubes_right");
+        if (right)
+            tmux(["select-pane", "-t", right]);
+    };
+    /** Show `id` on the right; the keyboard stays in the list. The one already showing is gone INTO. */
     const open = (id) => {
+        if (id === st.current) {
+            goIn();
+            return;
+        }
         const right = getSessionOption("@cubes_right");
         if (!right) {
             flash("the session pane is gone - run cubes again");
@@ -152,7 +166,6 @@ export async function runList() {
             flash(`could not open it: ${r.err || r.code}`);
             return;
         }
-        tmux(["select-pane", "-t", right]);
         st.current = id;
         setSessionOption("@cubes_current", id);
     };
@@ -209,12 +222,9 @@ export async function runList() {
                     open(st.selectedId);
                 break;
             case "tab":
-            case "ctrl-]": {
-                const right = getSessionOption("@cubes_right");
-                if (right)
-                    tmux(["select-pane", "-t", right]);
+            case "ctrl-]":
+                goIn();
                 break;
-            }
             case "right":
                 if (st.selectedId && !toggleFold(st.selectedId, true)) { /* a leaf: nothing to open */ }
                 break;
@@ -300,7 +310,7 @@ export async function runList() {
         const it = items[st.top + k.y - 2];
         if (!it || it.kind !== "session")
             return;
-        // A click on the fold arrow folds; anywhere else on the row opens it.
+        // A click on the fold arrow folds; anywhere else on the row shows it (and on the one showing, goes in).
         const arrowCol = 1 + strWidth(treePrefix(it)) + 1;
         if (it.children > 0 && k.x === arrowCol) {
             st.selectedId = it.row.id;

package/dist/tui/paneApp.js

@@ -1,8 +1,9 @@
 // The right pane of the split view: the session itself, under a header (tmux's pane border) that says
 // which one it is - name, group, runner, state - and stays current while you work in it.
 //
-// The list replaces this process (`respawn-pane -k`) to open another session, so it only ever holds
-// one. When an attach ends it SAYS so and waits: there is no automatic reconnect, by decision ("never
+// The list replaces this process (`respawn-pane -k`) to show another session, so it only ever holds
+// one - and it does that while the keyboard stays in the list, so this pane must never need focus to
+// get going. When an attach ends it SAYS so and waits: there is no automatic reconnect, by decision ("never
 // keep retrying to reattach a session") - `r` reconnects when the person chooses to.
 import { makeApi } from "../api.js";
 import { attach } from "../attach.js";
@@ -19,7 +20,7 @@ const focusList = () => {
     if (left)
         tmux(["select-pane", "-t", left]);
 };
-/** The header: `● Title · Group · runner · state`, as a tmux format (styles via #[...]). */
+/** The header: `● Title · Group · runner · state · F1 list`, as a tmux format (styles via #[...]). */
 export function headerFor(r, override) {
     const s = override ?? statusOf({ status: r.status ?? "running", activity_status: r.activity_status ?? null });
     const parts = [
@@ -27,6 +28,7 @@ export function headerFor(r, override) {
         fmtText(printable(r.group_name || r.package_name || "no group")),
         fmtText(printable(r.runner_name || "-")),
         `#[fg=colour${s.color}]${s.label}#[default]`,
+        "#[fg=colour240]F1 list#[default]", // the way back, where you look when you want it
     ];
     return parts.join(" #[fg=colour240]·#[default] ");
 }
@@ -125,7 +127,7 @@ async function sessionPane(id) {
                 readClipboardImage: () => readClipboardImage(),
                 clipboard: copyCmd ? { write: (text) => writeClipboard(copyCmd, text) } : null,
             }, row, {
-                onDetachKey: focusList,
+                detachKey: false, // ^] is Claude Code's; F1 (tmux) is the way back to the list
                 onCopied: (text) => {
                     setPaneOption("@cubes_header", `#[fg=colour78]✓ Copied ${[...text].length} characters to your clipboard#[default]`);
                     setTimeout(() => setHeader(row), 1500);
@@ -142,9 +144,10 @@ async function sessionPane(id) {
             { text: words.head, style: ESC.bold + ESC.fg(words.color) },
             { text: result.message, style: ESC.dim },
             { text: "" },
-            { text: `r  ${words.key}     ^]  back to the list` },
+            { text: `r  ${words.key}     F1  back to the list` },
         ]);
-        // Wait for the person: `r` goes round again, ^] / Esc / Tab hand focus back to the list.
+        // Wait for the person: `r` goes round again; Esc / Tab / ^] hand focus back to the list (as does
+        // F1, which tmux takes before it gets here). Nothing is attached now, so no key is Claude's.
         for (;;) {
             const k = await waitKey((k) => (k.kind === "char" && (k.ch === "r" || k.ch === "R")) || k.kind === "enter"
                 || k.kind === "ctrl-]" || k.kind === "escape" || k.kind === "tab");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.2.1",
-  "description": "Attach to your Cubes sessions from your own terminal (Warp, iTerm, Ghostty, anything).",
+  "version": "0.3.0",
+  "description": "The Cubes command line: your Cubes sessions in your own terminal (attach, a split view of all of them, image paste, clipboard, tab status and notifications), and Claude Code conversations moved between your computer and Cubes (import, export).",
   "type": "module",
   "bin": {
     "cubes": "dist/cli.js"
@@ -22,7 +22,13 @@
   "keywords": [
     "cubes",
     "claude",
+    "claude-code",
     "terminal",
+    "tmux",
+    "remote",
+    "sessions",
+    "import",
+    "export",
     "cli"
   ],
   "license": "UNLICENSED",