@hellix-ai/cubes 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,309 @@
+#!/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";
+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:
+  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
+  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.
+
+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);
+        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\``);
+    }
+}
+/** 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`);
+    exitAfterFlush(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", "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 ?? "",
+    ]);
+    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");
+}

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;
+}