@hellix-ai/cubes 0.2.2 → 0.3.0

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.2.2",
-  "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",