@kvbox/cli 0.0.0-stage → 0.5.6

package/dist/kvbox.js

@@ -0,0 +1,2057 @@
+#!/usr/bin/env node
+
+// ../shared/src/errors.ts
+var KvboxError = class extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "KvboxError";
+  }
+  exitCode;
+};
+var AmbiguousRefError = class extends KvboxError {
+  constructor(kind, name, slugs) {
+    super(`${kind} ${name} exists in ${slugs.slice(0, -1).join(", ")} and ${slugs.at(-1)}; say which with --org ${slugs[0]} or ${slugs[0]}/${name}`, 1);
+    this.name = "AmbiguousRefError";
+  }
+};
+
+// src/output.ts
+import pc from "picocolors";
+var color = pc.createColors(process.stdout.isTTY === true && !process.env["NO_COLOR"]);
+function json(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+var ANSI = /\x1b\[[0-9;]*m/g;
+var width = (s) => s.replace(ANSI, "").length;
+function table(rows, columns) {
+  if (rows.length === 0) return;
+  const cols = columns ?? Object.keys(rows[0]);
+  const cells = rows.map((r) => cols.map((c) => String(r[c] ?? "")));
+  const widths = cols.map((c, i) => Math.max(c.length, ...cells.map((r) => width(r[i]))));
+  const line = (parts) => parts.map((p, i) => p + " ".repeat(Math.max(0, widths[i] - width(p)))).join("  ").trimEnd();
+  process.stdout.write(color.dim(line(cols.map((c) => c.toUpperCase()))) + "\n");
+  for (const row of cells) process.stdout.write(line(row) + "\n");
+}
+function info(msg) {
+  process.stderr.write(msg + "\n");
+}
+function warn(msg) {
+  process.stderr.write(color.yellow(msg) + "\n");
+}
+async function confirm(question, yes) {
+  if (yes) return true;
+  if (!process.stdin.isTTY) {
+    warn("refusing without -y when stdin is not a terminal");
+    return false;
+  }
+  const { createInterface: createInterface2 } = await import("readline/promises");
+  const rl = createInterface2({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function gb(bytes) {
+  const g = bytes / 1024 ** 3;
+  if (g >= 1) return `${Number.isInteger(g) ? g : g.toFixed(1)} GB`;
+  return `${Math.round(bytes / 1024 ** 2)} MB`;
+}
+function gbShort(bytes) {
+  return gb(bytes).replace(" ", "");
+}
+function shape(vcpu, memMib, diskBytes) {
+  const cpuRam = `${vcpu}\xD7${gbShort(memMib * 1024 ** 2)}`;
+  return diskBytes === void 0 ? cpuRam : `${cpuRam} \xB7 ${gbShort(diskBytes)} disk`;
+}
+function boxName(name) {
+  return color.cyan(name);
+}
+function status(s) {
+  if (s === "running") return color.green(s);
+  if (s === "standby" || s === "hibernated") return color.yellow(s);
+  return color.dim(s);
+}
+function age(iso, now = Date.now()) {
+  const sec = Math.max(0, Math.floor((now - Date.parse(iso)) / 1e3));
+  if (sec < 60) return "just now";
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day3 = Math.floor(hr / 24);
+  if (day3 < 30) return `${day3}d ago`;
+  const month = Math.floor(day3 / 30);
+  if (month < 12) return `${month}mo ago`;
+  return `${Math.floor(day3 / 365)}y ago`;
+}
+function duration(seconds) {
+  const s = Math.max(0, Math.round(seconds));
+  if (s === 0) return "-";
+  const d = Math.floor(s / 86400);
+  const h = Math.floor(s % 86400 / 3600);
+  const m = Math.floor(s % 3600 / 60);
+  const sec = s % 60;
+  if (d > 0) return `${d}d ${h}h`;
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m ${sec}s`;
+  return `${sec}s`;
+}
+function hours(h) {
+  return h < 100 ? String(Math.round(h * 10) / 10) : String(Math.round(h));
+}
+function slugOf(owner) {
+  const at = owner.indexOf("@");
+  return at === -1 ? owner : owner.slice(0, at);
+}
+function pickRef(items, text, me2, kind = "box") {
+  if (text.includes("/")) return items.find((i) => text === `${slugOf(i.owner)}/${i.name}` || text === `${i.owner}/${i.name}`);
+  const named = items.filter((i) => i.name === text);
+  const own = named.find((i) => slugOf(i.owner) === me2);
+  if (own) return own;
+  const orgs = me2 === void 0 ? named : named.filter((i) => i.ownerKind !== "user");
+  if (orgs.length <= 1) return orgs[0];
+  throw new AmbiguousRefError(kind, text, orgs.map((i) => slugOf(i.owner)));
+}
+function shortRef(ref, owner) {
+  return ref.startsWith(`${owner}/`) ? ref.slice(owner.length + 1) : ref;
+}
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var SPINNER_DELAY_MS = 150;
+var SPINNER_FRAME_MS = 80;
+async function spin(message, work, opts = {}) {
+  const stream = opts.stream ?? process.stderr;
+  const promise = typeof work === "function" ? work() : work;
+  if (stream.isTTY !== true) return promise;
+  let frame = 0;
+  let drawn = false;
+  const draw = () => {
+    stream.write(`\r\x1B[K${color.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length])} ${message}`);
+    frame += 1;
+    drawn = true;
+  };
+  let interval;
+  const delay = setTimeout(() => {
+    draw();
+    interval = setInterval(draw, SPINNER_FRAME_MS);
+  }, opts.delayMs ?? SPINNER_DELAY_MS);
+  try {
+    return await promise;
+  } finally {
+    clearTimeout(delay);
+    if (interval !== void 0) clearInterval(interval);
+    if (drawn) stream.write("\r\x1B[K");
+  }
+}
+
+// src/program.ts
+import { Command as Command38 } from "commander";
+
+// ../shared/src/version.ts
+import { createRequire } from "module";
+function versionOf(srcFileUrl, injected) {
+  if (typeof injected === "string") return injected;
+  try {
+    const require2 = createRequire(srcFileUrl);
+    return require2("../package.json").version;
+  } catch {
+    return "0.0.0-dev";
+  }
+}
+
+// src/version.ts
+var VERSION = versionOf(import.meta.url, true ? "0.5.6" : void 0);
+
+// src/commands/vm/index.ts
+import { Command as Command15 } from "commander";
+
+// src/commands/vm/connect.ts
+import { spawnSync } from "child_process";
+import { Command as Command2 } from "commander";
+
+// src/cert.ts
+import { readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+
+// ../shared/src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+function kvboxHome() {
+  return process.env["KVBOX_HOME"] ?? join(homedir(), ".kvbox");
+}
+function paths(home = kvboxHome()) {
+  return {
+    home,
+    config: join(home, "config.json"),
+    /** The host's ledgers (SQLite via node:sqlite): usage events today. Boxes and snapshots stay files; see server core/db.ts. */
+    db: join(home, "kvbox.db"),
+    serverSock: join(home, "server.sock"),
+    serverPid: join(home, "server.pid"),
+    serverLog: join(home, "server.log"),
+    /** The CLI's login to the control plane (`kvbox login`): url, bearer token, user. Mode 600. */
+    cli: join(home, "cli.json"),
+    ssh: join(home, "ssh"),
+    sshKey: join(home, "ssh", "id_ed25519"),
+    /** The device key signed by the control plane's CA (#51); ssh loads it by itself next to `-i id_ed25519`. */
+    sshCert: join(home, "ssh", "id_ed25519-cert.pub"),
+    /** Host keys of the cloud boxes this laptop connected to, one entry per box (`connect`, #21). */
+    sshKnownHosts: join(home, "ssh", "known_hosts"),
+    /** The host's self-signed TLS identity for the control plane (`kvbox-server join`): pinned there by fingerprint. */
+    tls: join(home, "tls"),
+    tlsKey: join(home, "tls", "key.pem"),
+    tlsCert: join(home, "tls", "cert.pem"),
+    /** The host's WireGuard tunnel to its relay (`kvbox server relay`, #50): the conf net-setup.sh installs for wg-quick. Mode 600. */
+    relay: join(home, "relay"),
+    relayConf: join(home, "relay", "kvbox.conf"),
+    bin: join(home, "bin"),
+    firecracker: join(home, "bin", "firecracker"),
+    /** Firecracker's snapshot-editor, from the same release: merges a diff snapshot onto a full memory image. */
+    snapshotEditor: join(home, "bin", "snapshot-editor"),
+    assets: join(home, "assets"),
+    kernel: join(home, "assets", "vmlinux"),
+    /** Symlink to the current base image, assets/rootfs-<version>.ext4; boxes keep using the version they were made from. */
+    rootfs: join(home, "assets", "rootfs.ext4"),
+    baseImage: (version) => join(home, "assets", `rootfs-${version}.ext4`),
+    machines: join(home, "machines"),
+    snapshots: join(home, "snapshots"),
+    /** Boxes and snapshots are filed by owner: machines/<owner>/<name>. The owner is part of a box's identity. */
+    ownerMachines: (owner) => join(home, "machines", owner),
+    ownerSnapshots: (owner) => join(home, "snapshots", owner),
+    machine: (owner, name) => {
+      const dir = join(home, "machines", owner, name);
+      return {
+        dir,
+        meta: join(dir, "meta.json"),
+        /** The box's writable layer, stacked on the read-only base image inside the guest. */
+        overlay: join(dir, "overlay.ext4"),
+        /**
+         * The box's memory as of its last snapshot (a hard link to that snapshot's `mem`, never modified).
+         * The next snapshot is a diff of the pages dirtied since, merged onto this. Absent after a boot.
+         */
+        memBase: join(dir, "mem.base"),
+        /** `kvbox hibernate`: the box's memory image and VM state while it is hibernated; gone again after `wake` or `stop`. */
+        hibernateDir: join(dir, "hibernate"),
+        hibernateVmstate: join(dir, "hibernate", "vmstate"),
+        hibernateMem: join(dir, "hibernate", "mem"),
+        sock: join(dir, "fc.sock"),
+        /** Firecracker's vsock endpoint: the host connects here to reach kvbox-agent inside the box (core/agent.ts). */
+        vsock: join(dir, "vsock.sock"),
+        log: join(dir, "fc.log")
+      };
+    },
+    snapshot: (owner, name) => {
+      const dir = join(home, "snapshots", owner, name);
+      return {
+        dir,
+        meta: join(dir, "meta.json"),
+        vmstate: join(dir, "vmstate"),
+        mem: join(dir, "mem"),
+        /** Copy of the box's overlay at the moment of the snapshot; the base image is referenced by version in meta.json. */
+        overlay: join(dir, "overlay.ext4")
+      };
+    }
+  };
+}
+
+// src/session.ts
+import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
+import { z } from "zod";
+var SessionSchema = z.object({
+  url: z.string(),
+  token: z.string(),
+  user: z.string(),
+  /** When the SSH certificate at paths().sshCert stops being accepted (ISO); absent before the first login with a key. */
+  sshCertExpires: z.string().optional(),
+  /** Whose boxes that certificate opens (`<slug>@<realm>`, the user and their orgs); absent with `sshCertExpires`. */
+  sshCertPrincipals: z.array(z.string()).optional()
+});
+async function readSession(p = paths()) {
+  let text;
+  try {
+    text = await readFile(p.cli, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    return SessionSchema.parse(JSON.parse(text));
+  } catch {
+    throw new KvboxError(`${p.cli} is unreadable; run: kvbox logout (then log in again)`);
+  }
+}
+async function writeSession(session, p = paths()) {
+  await mkdir(p.home, { recursive: true });
+  await writeFile(p.cli, JSON.stringify(session, null, 2) + "\n", { mode: 384 });
+  await chmod(p.cli, 384);
+}
+async function clearSession(p = paths()) {
+  await rm(p.cli, { force: true });
+}
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname.startsWith("127.") || hostname === "[::1]";
+}
+function normalizeUrl(input) {
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(input) ? input : `https://${input}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    throw new KvboxError(`not a URL: ${input}`);
+  }
+  if (!/^https?:$/.test(url.protocol) || url.hostname === "" || /\s/.test(input)) throw new KvboxError(`not a URL: ${input}`);
+  if (url.protocol === "http:" && !isLoopback(url.hostname)) {
+    throw new KvboxError(`${input}: use https (plain http is only allowed for localhost)`);
+  }
+  return url.origin + url.pathname.replace(/\/+$/, "");
+}
+
+// src/cert.ts
+var RENEW_BEFORE_MS = 60 * 60 * 1e3;
+async function writeCert(cert, p = paths()) {
+  await writeFile2(p.sshCert, cert.trim() + "\n", { mode: 420 });
+}
+async function renewAfterRefusal(client, kept, owner, p = paths()) {
+  if (kept !== "kept") return false;
+  await ensureCert(client, p, Date.now(), { owner, force: true });
+  return true;
+}
+async function removeCert(p = paths()) {
+  await rm2(p.sshCert, { force: true });
+}
+async function ensureCert(client, p = paths(), now = Date.now(), opts = {}) {
+  if (client.target.kind !== "cloud") return "local";
+  const session = await readSession(p);
+  if (!session) return "local";
+  const expires = session.sshCertExpires ? new Date(session.sshCertExpires).getTime() : 0;
+  const onDisk = await readFile2(p.sshCert, "utf8").then(() => true, () => false);
+  const names = opts.owner === void 0 || (session.sshCertPrincipals ?? []).includes(opts.owner);
+  if (onDisk && expires - now > RENEW_BEFORE_MS && names && !opts.force) return "kept";
+  const publicKey = await readFile2(`${p.sshKey}.pub`, "utf8").catch(() => null);
+  if (publicKey === null) throw new KvboxError(`could not renew your SSH certificate: no key at ${p.sshKey}.pub; run: kvbox login`);
+  let signed;
+  try {
+    signed = await client.sshCert({ publicKey: publicKey.trim() });
+  } catch (err) {
+    throw new KvboxError(`could not renew your SSH certificate: ${err.message}`);
+  }
+  await writeCert(signed.cert, p);
+  await writeSession({ ...session, sshCertExpires: signed.expires, sshCertPrincipals: signed.principals }, p);
+  if (opts.owner !== void 0 && !signed.principals.includes(opts.owner)) {
+    const slug = opts.owner.split("@")[0];
+    const sameSlugElsewhere = signed.principals.find((pr) => pr.split("@")[0] === slug && pr !== opts.owner);
+    const why = sameSlugElsewhere ? `the control plane signs for ${sameSlugElsewhere} but the box's host qualifies its owner as ${opts.owner}: the control plane's name (KVBOX_CLOUD_NAME) changed after the host joined` : `you are not a member of ${slug} (a platform admin reaches org boxes over the API, not over SSH)`;
+    throw new KvboxError(`your SSH certificate does not name ${opts.owner}: ${why}`);
+  }
+  return "renewed";
+}
+
+// src/client.ts
+import { spawn } from "child_process";
+import { openSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile3, stat } from "fs/promises";
+import { setTimeout as sleep } from "timers/promises";
+import { Agent, request } from "undici";
+import { z as z3 } from "zod";
+
+// ../shared/src/api.ts
+import { z as z2 } from "zod";
+
+// ../shared/src/sizes.ts
+var SIZES = {
+  s: { vcpu: 2, memMib: 4096, diskGib: 8 },
+  m: { vcpu: 4, memMib: 8192, diskGib: 16 },
+  l: { vcpu: 8, memMib: 16384, diskGib: 32 }
+};
+var SIZE_NAMES = Object.keys(SIZES);
+function parseMib(text) {
+  const m = /^\s*(\d+(?:\.\d+)?)\s*([gm]i?b?)?\s*$/i.exec(text);
+  if (!m) return void 0;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? "g").toLowerCase();
+  const mib = unit.startsWith("m") ? n : n * 1024;
+  return Number.isInteger(mib) && mib > 0 ? mib : void 0;
+}
+
+// ../shared/src/api.ts
+var SizeSchema = z2.enum(SIZE_NAMES);
+var BOX_SSH_USER = "kvbox";
+var BoxStatusSchema = z2.enum(["running", "standby", "hibernated", "stopped", "unknown"]);
+var MachineSchema = z2.object({
+  /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
+  id: z2.string(),
+  name: z2.string(),
+  /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
+  owner: z2.string(),
+  ip: z2.string(),
+  mac: z2.string(),
+  pid: z2.number().int().nullable(),
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  diskBytes: z2.number().int(),
+  // the box's own writable disk, as the guest sees it
+  diskUsedBytes: z2.number().int(),
+  // what that sparse file really occupies on the host
+  base: z2.string(),
+  // base image version the box's overlay stacks on
+  createdAt: z2.string(),
+  source: z2.string(),
+  // "base" or "snapshot:<name>"
+  status: BoxStatusSchema,
+  /**
+   * Public TCP port on the host that reaches the box's SSH while it runs (#49). Only boxes made
+   * through a control plane have one; the control plane adds the host's address for `connect` (#21).
+   */
+  sshPort: z2.number().int().optional(),
+  /**
+   * Where `ssh` reaches the box from outside: the host's public address and that port (#21). Only
+   * the control plane fills it in (a host does not know its own public address); absent for a box
+   * whose host reported no port or did not answer.
+   */
+  ssh: z2.object({ host: z2.string(), port: z2.number().int(), user: z2.string() }).optional(),
+  /** Whether the owner slug is a user or an org. Only the control plane knows; it fills it in on `GET /machines`. */
+  ownerKind: z2.enum(["user", "org"]).optional()
+});
+var CreateMachineRequest = z2.object({
+  name: z2.string().optional(),
+  /** Ignored over the local socket (the caller is the host owner); the control plane sets it over HTTPS. */
+  owner: z2.string().optional(),
+  size: SizeSchema.optional(),
+  from: z2.string().optional(),
+  force: z2.boolean().optional(),
+  /**
+   * Extra authorized_keys lines for the box, on top of the host's own key: the control plane sends
+   * its SSH CA as one `cert-authority …` line (#51). Written into the box's authorized_keys at every
+   * boot (#49); a host older than that ignores them.
+   */
+  sshKeys: z2.array(z2.string()).optional()
+});
+var SetSshKeysRequest = z2.object({
+  sshKeys: z2.array(z2.string())
+});
+var RescaleMachineRequest = z2.object({
+  size: SizeSchema.optional(),
+  vcpu: z2.number().int().min(1).max(64).optional(),
+  memMib: z2.number().int().min(256).optional(),
+  diskGib: z2.number().int().min(1).optional()
+});
+var SnapshotSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  source: z2.string(),
+  // the box it was taken from, as owner/name
+  base: z2.string(),
+  // base image version the overlay stacks on; a restore needs the same one
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  sizeBytes: z2.number().int(),
+  // what vmstate + mem + overlay really occupy on the host
+  createdAt: z2.string()
+});
+var CreateSnapshotRequest = z2.object({
+  box: z2.string(),
+  name: z2.string()
+});
+var CapacitySchema = z2.object({
+  hostMemMib: z2.number().int(),
+  hostCores: z2.number().int(),
+  reservedMemMib: z2.number().int(),
+  reservedVcpu: z2.number().int(),
+  running: z2.number().int()
+});
+var HealthSchema = z2.object({
+  ok: z2.literal(true),
+  version: z2.string(),
+  pid: z2.number().int(),
+  /** Base image version new boxes get (null when the host has no usable base image yet). */
+  base: z2.string().nullable(),
+  /** Owner that boxes made over the local socket get (the Unix user running the server). */
+  owner: z2.string(),
+  /** The control plane this host joined (null when none). */
+  controlPlane: z2.object({
+    /** Realm name, e.g. kvbox.sh. */
+    name: z2.string(),
+    url: z2.string(),
+    /** Where this host answers the control plane. */
+    hostUrl: z2.string()
+  }).nullable(),
+  /** The relay this host reaches the internet through (#50); null when it has its own public address. Older servers omit it. */
+  relay: z2.object({
+    name: z2.string(),
+    /** The public IP the relay owns for this host. */
+    publicIp: z2.string(),
+    /** The relay's WireGuard endpoint the tunnel dials. */
+    endpoint: z2.string()
+  }).nullable().optional()
+});
+var MachineUsageSchema = z2.object({
+  name: z2.string(),
+  owner: z2.string(),
+  status: BoxStatusSchema,
+  window: z2.object({ from: z2.string(), to: z2.string() }),
+  seconds: z2.object({
+    running: z2.number().int(),
+    standby: z2.number().int(),
+    hibernated: z2.number().int(),
+    stopped: z2.number().int()
+  }),
+  vcpuHours: z2.number(),
+  ramGibHours: z2.number(),
+  diskGibHours: z2.number(),
+  cost: z2.object({ amount: z2.number(), currency: z2.string() }).optional(),
+  /** Stops the server did not witness (Firecracker died, host rebooted) and dated to when it noticed. */
+  estimatedStops: z2.number().int(),
+  historyFrom: z2.string().nullable()
+});
+var UsageStatusSchema = z2.enum([...BoxStatusSchema.options, "removed"]);
+var BoxUsageSchema = MachineUsageSchema.omit({ window: true, status: true }).extend({
+  /** The host's box id; a name removed and recreated appears twice, with two ids. */
+  id: z2.string(),
+  status: UsageStatusSchema,
+  /** Through a control plane: whether the owner slug is a user's or an org's (what `kvbox ls` shows). */
+  ownerKind: z2.enum(["user", "org"]).optional()
+});
+var UsageReportSchema = z2.object({
+  window: z2.object({ from: z2.string(), to: z2.string() }),
+  boxes: z2.array(BoxUsageSchema),
+  totals: z2.object({
+    seconds: MachineUsageSchema.shape.seconds,
+    vcpuHours: z2.number(),
+    ramGibHours: z2.number(),
+    diskGibHours: z2.number(),
+    cost: z2.object({ amount: z2.number(), currency: z2.string() }).optional()
+  })
+});
+var UsageEventRowSchema = z2.object({
+  id: z2.number().int(),
+  boxId: z2.string(),
+  owner: z2.string(),
+  name: z2.string(),
+  at: z2.string(),
+  state: z2.enum(["running", "standby", "hibernated", "stopped"]),
+  vcpu: z2.number().int(),
+  memMib: z2.number().int(),
+  diskGib: z2.number().int(),
+  by: z2.string()
+});
+var UsageEventsResponseSchema = z2.object({
+  ledger: z2.string().min(1),
+  events: z2.array(UsageEventRowSchema),
+  next: z2.number().int()
+});
+var ApiErrorSchema = z2.object({
+  error: z2.string()
+});
+var DEFAULT_CLOUD_URL = "https://api.kvbox.sh";
+var CloudUserSchema = z2.object({
+  /** The handle: what hosts file boxes under (`<username>@<control plane>`). Lowercase, no `@` or `/`. */
+  username: z2.string(),
+  /** Display name, free text ("Alexandru Ghiura"). */
+  name: z2.string(),
+  /** Login identity, unique. */
+  email: z2.string(),
+  role: z2.enum(["admin", "user"]),
+  createdAt: z2.string()
+});
+var ORG_ROLES = ["owner", "admin", "member"];
+var OrgRoleSchema = z2.enum(ORG_ROLES);
+var CloudOrgSchema = z2.object({
+  slug: z2.string(),
+  /** Display name; the slug never changes, this may. */
+  name: z2.string(),
+  createdAt: z2.string()
+});
+var OrgMembershipSchema = CloudOrgSchema.extend({ role: OrgRoleSchema });
+var OrgMemberSchema = z2.object({
+  username: z2.string(),
+  name: z2.string(),
+  role: OrgRoleSchema,
+  addedAt: z2.string()
+});
+var OrgDetailSchema = CloudOrgSchema.extend({ members: z2.array(OrgMemberSchema) });
+var CreateOrgRequestSchema = z2.object({
+  slug: z2.string().min(1),
+  name: z2.string().min(1)
+});
+var RenameOrgRequestSchema = z2.object({ name: z2.string().min(1) });
+var AddMemberRequestSchema = z2.object({
+  username: z2.string().min(1),
+  role: OrgRoleSchema.default("member")
+});
+var SetRoleRequestSchema = z2.object({ role: OrgRoleSchema });
+var MeResponseSchema = CloudUserSchema.extend({ orgs: z2.array(OrgMembershipSchema) });
+var LoginRequestSchema = z2.object({
+  email: z2.string().min(1),
+  password: z2.string().min(1),
+  publicKey: z2.string().optional()
+});
+var SignupRequestSchema = z2.object({
+  username: z2.string().min(1),
+  name: z2.string().min(1),
+  email: z2.string().min(1),
+  password: z2.string().min(1)
+});
+var LoginResponseSchema = z2.object({
+  token: z2.string(),
+  user: CloudUserSchema,
+  sshCert: z2.string().optional(),
+  sshCertExpires: z2.string().optional(),
+  /** Whose boxes the certificate opens: `<slug>@<realm>` for the user and each org they are in (orgs phase 4). */
+  sshCertPrincipals: z2.array(z2.string()).optional()
+});
+var SshCertRequestSchema = z2.object({
+  publicKey: z2.string().min(1)
+});
+var SshCertResponseSchema = z2.object({
+  cert: z2.string(),
+  expires: z2.string(),
+  principals: z2.array(z2.string())
+});
+var SshCaResponseSchema = z2.object({
+  publicKey: z2.string(),
+  /** CAs replaced by `ca rotate` (#55), newest first; a box still holding one of these has not had `kvbox server trust-ca` run on its host. */
+  retired: z2.array(z2.object({ publicKey: z2.string(), retiredAt: z2.string() })).optional()
+});
+var HostSshCaResponseSchema = z2.object({
+  publicKey: z2.string()
+});
+var CloudCaSchema = z2.object({
+  controlPlane: z2.string(),
+  publicKey: z2.string(),
+  fingerprint: z2.string()
+});
+var TrustCaRequestSchema = z2.object({
+  publicKey: z2.string().min(1)
+});
+var SshKeysAppliedSchema = z2.enum(["now", "start", "wake", "resume", "later"]);
+var TrustCaReportSchema = z2.object({
+  publicKey: z2.string(),
+  fingerprint: z2.string(),
+  /** The guest trusts the CA now. */
+  updated: z2.array(z2.string()),
+  /** meta.json has the line; the guest gets it at `when`. */
+  pending: z2.array(z2.object({ box: z2.string(), when: SshKeysAppliedSchema, why: z2.string().optional() })),
+  failed: z2.array(z2.object({ box: z2.string(), error: z2.string() })),
+  /** Local boxes, untouched: they trust the host's key only. */
+  local: z2.number().int()
+});
+var HostJoinRequestSchema = z2.object({
+  token: z2.string().min(1),
+  name: z2.string().min(1),
+  url: z2.string().url(),
+  fingerprint: z2.string().regex(/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/),
+  publicAddress: z2.string().min(1)
+});
+var HostJoinResponseSchema = z2.object({
+  hostSecret: z2.string(),
+  controlPlane: z2.object({ name: z2.string() })
+});
+var CloudHostSchema = z2.object({
+  name: z2.string(),
+  url: z2.string(),
+  publicAddress: z2.string(),
+  joinedAt: z2.string(),
+  lastSeenAt: z2.string().nullable(),
+  capacity: CapacitySchema.nullable()
+});
+
+// src/kvm.ts
+import { accessSync, constants, readFileSync, statSync } from "fs";
+import { userInfo } from "os";
+var KVM_DEVICE = "/dev/kvm";
+function serverLauncher(opts = {}) {
+  const device = opts.device ?? KVM_DEVICE;
+  const plain = { cmd: "kvbox-server", args: ["start"] };
+  try {
+    accessSync(device, constants.R_OK | constants.W_OK);
+    return plain;
+  } catch (err) {
+    const code = err.code;
+    if (code !== "EACCES" && code !== "EPERM") return plain;
+  }
+  let gid;
+  try {
+    gid = statSync(device).gid;
+  } catch {
+    return plain;
+  }
+  const group = groupWithMember(gid, opts.user ?? userInfo().username, opts.groupFile ?? "/etc/group");
+  if (group === void 0) return plain;
+  return { cmd: "sg", args: [group, "-c", "kvbox-server start"], viaGroup: group };
+}
+function groupWithMember(gid, user, groupFile) {
+  let text;
+  try {
+    text = readFileSync(groupFile, "utf8");
+  } catch {
+    return void 0;
+  }
+  for (const line of text.split("\n")) {
+    const [name, , id, members = ""] = line.split(":");
+    if (name === void 0 || id === void 0 || Number.parseInt(id, 10) !== gid) continue;
+    return members.split(",").includes(user) ? name : void 0;
+  }
+  return void 0;
+}
+
+// src/client.ts
+var ORG_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+function orgOption(opts) {
+  if (opts.org === void 0 || opts.org === "") return void 0;
+  if (!ORG_SLUG_RE.test(opts.org)) throw new KvboxError(`${opts.org}: not an org slug (lowercase letters, digits, '.', '_' or '-')`);
+  return opts.org;
+}
+async function resolveTarget(opts, p = paths()) {
+  if (!opts.local) {
+    const session = await readSession(p);
+    if (session) {
+      const org = orgOption(opts);
+      return { kind: "cloud", url: session.url, token: session.token, user: session.user, ...org === void 0 ? {} : { org } };
+    }
+  }
+  return { kind: "local", socketPath: p.serverSock };
+}
+var ServerClient = class {
+  constructor(target, opts = {}) {
+    this.target = target;
+    this.autoStart = opts.autoStart ?? true;
+    if (target.kind === "local") {
+      this.dispatcher = new Agent({ connect: { socketPath: target.socketPath } });
+      this.base = "http://kvbox";
+    } else {
+      this.dispatcher = new Agent();
+      this.base = target.url;
+    }
+  }
+  target;
+  dispatcher;
+  base;
+  autoStart;
+  startedOnce = false;
+  async call(method, path, schema, body) {
+    const headers = {};
+    if (body !== void 0) headers["content-type"] = "application/json";
+    if (this.target.kind === "cloud" && this.target.token !== "") headers["authorization"] = `Bearer ${this.target.token}`;
+    if (this.target.kind === "cloud" && this.target.org !== void 0) headers["x-kvbox-org"] = this.target.org;
+    let res;
+    try {
+      res = await request(this.base + path, {
+        dispatcher: this.dispatcher,
+        method,
+        headers,
+        body: body === void 0 ? null : JSON.stringify(body)
+      });
+    } catch (err) {
+      const code = err.code ?? err.cause;
+      if (this.target.kind === "local") {
+        if (this.autoStart && !this.startedOnce) {
+          this.startedOnce = true;
+          await spin("starting kvbox-server\u2026", startLocalServer(paths(), 5e3));
+          return this.call(method, path, schema, body);
+        }
+        throw new KvboxError(`kvbox-server is not running (${String(code)}); start it with: kvbox server start`);
+      }
+      throw new KvboxError(cloudDown(this.target.url, String(code)));
+    }
+    const text = await res.body.text();
+    const where = this.target.kind === "cloud" ? hostOf(this.target.url) : "kvbox-server";
+    if (res.statusCode >= 300) {
+      const parsed = ApiErrorSchema.safeParse(safeJson(text) ?? {});
+      if (!parsed.success) throw new KvboxError(`${where} answered ${res.statusCode}`);
+      if (this.target.kind === "cloud" && this.target.token !== "") {
+        if (res.statusCode === 401) throw new KvboxError("session expired: kvbox login");
+        if (res.statusCode === 404 && this.target.org !== void 0 && parsed.data.error === `org ${this.target.org}: not found`) {
+          throw new KvboxError(`${parsed.data.error} (you are not in it, or it is gone)`);
+        }
+      }
+      throw new KvboxError(parsed.data.error, res.statusCode === 501 ? 2 : 1);
+    }
+    if (text === "") return schema.parse(void 0);
+    const json2 = safeJson(text);
+    if (json2 === void 0) throw new KvboxError(`${where} answered ${res.statusCode} with something that is not JSON`);
+    return schema.parse(json2);
+  }
+  health() {
+    return this.call("GET", "/health", HealthSchema);
+  }
+  capacity() {
+    return this.call("GET", "/capacity", CapacitySchema);
+  }
+  /** Through a control plane: every box the user can see, or the `--org` org's. */
+  listMachines() {
+    return this.call("GET", "/machines", z3.array(MachineSchema));
+  }
+  createMachine(req) {
+    return this.call("POST", "/machines", MachineSchema, req);
+  }
+  stopMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/stop`, MachineSchema);
+  }
+  startMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/start`, MachineSchema);
+  }
+  pauseMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/pause`, MachineSchema);
+  }
+  resumeMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/resume`, MachineSchema);
+  }
+  hibernateMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/hibernate`, MachineSchema);
+  }
+  wakeMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/wake`, MachineSchema);
+  }
+  updateMachine(name) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/update`, MachineSchema);
+  }
+  rescaleMachine(name, req) {
+    return this.call("POST", `/machines/${encodeURIComponent(name)}/rescale`, MachineSchema, req);
+  }
+  /** `since`: an ISO date, already validated; the server counts from the box's creation without it. */
+  machineUsage(name, since) {
+    const query = since === void 0 ? "" : `?since=${encodeURIComponent(since)}`;
+    return this.call("GET", `/machines/${encodeURIComponent(name)}/usage${query}`, MachineUsageSchema);
+  }
+  /** Every box of the caller over the window (#41 on a host, #42 through a control plane); dates as the user wrote them. */
+  usageReport(since, until) {
+    const q = new URLSearchParams();
+    if (since !== void 0) q.set("since", since);
+    if (until !== void 0) q.set("until", until);
+    const query = q.size === 0 ? "" : `?${q.toString()}`;
+    return this.call("GET", `/usage${query}`, UsageReportSchema);
+  }
+  deleteMachine(name) {
+    return this.call("DELETE", `/machines/${encodeURIComponent(name)}`, z3.undefined());
+  }
+  listSnapshots() {
+    return this.call("GET", "/snapshots", z3.array(SnapshotSchema));
+  }
+  createSnapshot(req) {
+    return this.call("POST", "/snapshots", SnapshotSchema, req);
+  }
+  deleteSnapshot(name) {
+    return this.call("DELETE", `/snapshots/${encodeURIComponent(name)}`, z3.undefined());
+  }
+  // ---- control plane only (`kvbox login`, `logout`, `whoami`) ----
+  login(req) {
+    return this.call("POST", "/login", LoginResponseSchema, req);
+  }
+  logout() {
+    return this.call("POST", "/logout", z3.unknown()).then(() => void 0);
+  }
+  me() {
+    return this.call("GET", "/me", MeResponseSchema);
+  }
+  // ---- orgs (`kvbox org …`) ----
+  listOrgs() {
+    return this.call("GET", "/orgs", z3.array(OrgMembershipSchema));
+  }
+  createOrg(req) {
+    return this.call("POST", "/orgs", CloudOrgSchema, req);
+  }
+  getOrg(slug) {
+    return this.call("GET", `/orgs/${encodeURIComponent(slug)}`, OrgDetailSchema);
+  }
+  deleteOrg(slug) {
+    return this.call("DELETE", `/orgs/${encodeURIComponent(slug)}`, z3.undefined());
+  }
+  addMember(slug, req) {
+    return this.call("POST", `/orgs/${encodeURIComponent(slug)}/members`, z3.undefined(), req);
+  }
+  setRole(slug, username, role) {
+    return this.call("PATCH", `/orgs/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, z3.unknown(), { role }).then(() => void 0);
+  }
+  removeMember(slug, username) {
+    return this.call("DELETE", `/orgs/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, z3.undefined());
+  }
+  /** Sign this machine's key again (#51); the key must be one the user logged in with. */
+  sshCert(req) {
+    return this.call("POST", "/ssh/cert", SshCertResponseSchema, req);
+  }
+  sshCa() {
+    return this.call("GET", "/ssh/ca", SshCaResponseSchema);
+  }
+  /** This host's socket only (#55): the CA its control plane says boxes should trust. */
+  cloudCa() {
+    return this.call("GET", "/ssh/cloud-ca", CloudCaSchema);
+  }
+  /** This host's socket only (#55): make every cloud box on it trust this CA. */
+  trustCa(req) {
+    return this.call("POST", "/ssh/trust-ca", TrustCaReportSchema, req);
+  }
+  async close() {
+    await this.dispatcher.close();
+  }
+};
+function cloudDown(url, code) {
+  const host = hostOf(url);
+  const hint = host.endsWith("kvbox.sh") ? "check status.kvbox.sh" : "use --local for this machine, or kvbox logout";
+  return `${host} is not available or is down (${code}). You are logged in there, so kvbox talks to it instead of this machine; ${hint}`;
+}
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+async function wakeUp(client, box, name) {
+  switch (box.status) {
+    case "standby":
+      info(`box ${name} is in standby; resuming it`);
+      return spin(`resuming ${name}\u2026`, client.resumeMachine(name));
+    case "hibernated":
+      info(`box ${name} is hibernated; waking it`);
+      return spin(`waking ${name} (loading its memory from disk)\u2026`, client.wakeMachine(name));
+    case "stopped":
+      info(`box ${name} is stopped; starting it`);
+      return spin(`booting ${name}\u2026`, client.startMachine(name));
+    default:
+      return box;
+  }
+}
+var me = (client) => client.target.kind === "cloud" ? client.target.user : void 0;
+async function clientFor(opts, client = {}) {
+  return new ServerClient(await resolveTarget(opts), client);
+}
+function sshEndpoint(box, target) {
+  if (target.kind === "local") return { host: box.ip, port: 22, user: BOX_SSH_USER };
+  if (box.ssh === void 0) throw new KvboxError(`box ${box.name} has no public SSH port`);
+  return { ...box.ssh, alias: `${box.id}.${box.ssh.host}` };
+}
+function sshArgs(ep, p = paths()) {
+  const hostKey = ep.alias === void 0 ? ["-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null"] : ["-o", "StrictHostKeyChecking=accept-new", "-o", `UserKnownHostsFile=${p.sshKnownHosts}`, "-o", `HostKeyAlias=${ep.alias}`];
+  return [
+    "-i",
+    p.sshKey,
+    "-p",
+    String(ep.port),
+    ...hostKey,
+    "-o",
+    "LogLevel=ERROR",
+    "-o",
+    "SetEnv=LC_ALL=C.UTF-8",
+    `${ep.user}@${ep.host}`
+  ];
+}
+async function waitForSsh(ep, timeoutMs = 3e4) {
+  const { connect } = await import("net");
+  const deadline = Date.now() + timeoutMs;
+  const attempt = () => new Promise((resolve) => {
+    const sock = connect({ host: ep.host, port: ep.port, timeout: 1e3 });
+    sock.once("connect", () => {
+      sock.destroy();
+      resolve(true);
+    });
+    sock.once("timeout", () => {
+      sock.destroy();
+      resolve(false);
+    });
+    sock.once("error", () => resolve(false));
+  });
+  while (Date.now() < deadline) {
+    if (await attempt()) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new KvboxError(`box at ${ep.host}:${ep.port} did not answer within ${Math.round(timeoutMs / 1e3)}s`);
+}
+var NOT_A_HOST_HINT = "kvbox-server is not installed, so this machine is not a kvbox host. Set it up with install-server.sh, or log in to the cloud with: kvbox login";
+async function lastErrorLine(logPath) {
+  const { readFile: readFile6 } = await import("fs/promises");
+  const text = await readFile6(logPath, "utf8").catch(() => "");
+  const lines = text.trimEnd().split("\n").slice(-20).reverse();
+  return lines.find((l) => l.startsWith("error: "))?.slice("error: ".length);
+}
+async function startLocalServer(p = paths(), timeoutMs = 5e3) {
+  await mkdir2(p.home, { recursive: true });
+  const log = openSync(p.serverLog, "a");
+  const launcher = serverLauncher();
+  const child = spawn(launcher.cmd, launcher.args, { detached: true, stdio: ["ignore", log, log] });
+  const failed = new Promise((_, reject) => {
+    child.once("error", (err) => {
+      reject(new KvboxError(err.code === "ENOENT" && launcher.viaGroup === void 0 ? NOT_A_HOST_HINT : `could not start kvbox-server: ${err.message}`));
+    });
+    child.once("exit", (code) => {
+      void lastErrorLine(p.serverLog).then((why) => {
+        reject(new KvboxError(why === void 0 ? `kvbox-server exited with code ${String(code)} before listening; see ${p.serverLog}` : `kvbox-server could not start: ${why}`));
+      });
+    });
+  });
+  const ready = (async () => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (await stat(p.serverSock).then(() => true, () => false)) {
+        const probe = new ServerClient({ kind: "local", socketPath: p.serverSock }, { autoStart: false });
+        try {
+          await probe.health();
+          return;
+        } catch {
+        } finally {
+          await probe.close();
+        }
+      }
+      await sleep(100);
+    }
+    throw new KvboxError(`kvbox-server did not start within ${timeoutMs / 1e3}s; see ${p.serverLog}`);
+  })();
+  await Promise.race([ready, failed]);
+  child.removeAllListeners("exit");
+  child.unref();
+  const pid = Number.parseInt(await readFile3(p.serverPid, "utf8").catch(() => ""), 10);
+  return { pid: Number.isNaN(pid) ? child.pid ?? -1 : pid, socketPath: p.serverSock, viaGroup: launcher.viaGroup };
+}
+
+// src/commands/vm/new.ts
+import { Command, Option } from "commander";
+var newCommand = new Command("new").description("boot a new box from the base image or a snapshot").argument("[name]", "box name (box1, box2, \u2026 when omitted)").addOption(new Option("-s, --size <size>", "box size (default: server config, s)").choices(SIZE_NAMES)).option("-f, --from <snapshot>", "start from a snapshot instead of the base image").option("--force", "skip the capacity guard").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const what = opts.from !== void 0 ? `restoring ${name ?? "a new box"} from snapshot ${opts.from}\u2026` : `booting ${name ?? "a new box"}\u2026`;
+    const box = await spin(what, client.createMachine({
+      ...name !== void 0 ? { name } : {},
+      ...opts.size !== void 0 ? { size: opts.size } : {},
+      ...opts.from !== void 0 ? { from: opts.from } : {},
+      ...opts.force ? { force: true } : {}
+    }));
+    if (opts.json) {
+      json(box);
+      return;
+    }
+    const user = client.target.kind === "cloud" ? client.target.user : void 0;
+    process.stdout.write(`${box.name}
+`);
+    info(`${color.green("\u2713")} ${describe(box, user)}`);
+    if (opts.from !== void 0) info(`  connect with: kvbox connect ${displayName(box, user)}   (already up: everything that ran in the snapshot is running)`);
+    else info(`  connect with: kvbox connect ${displayName(box, user)}   (SSH is up a couple of seconds after boot)`);
+  } finally {
+    await client.close();
+  }
+});
+function displayName(box, user) {
+  return user !== void 0 && slugOf(box.owner) !== user ? `${slugOf(box.owner)}/${box.name}` : box.name;
+}
+function describe(box, user) {
+  const from = box.source.startsWith("snapshot:") ? ` from snapshot ${shortRef(box.source.slice("snapshot:".length), box.owner)}` : "";
+  return `box ${color.bold(displayName(box, user))} is ${box.status} at ${box.ip}${from}: ${box.vcpu} vCPU, ${gb(box.memMib * 1024 ** 2)} RAM, ${gb(box.diskBytes)} disk`;
+}
+
+// src/commands/vm/connect.ts
+var SSH_FAILED = 255;
+var connectCommand = new Command2("connect").alias("cn").description("open a shell in a box over SSH (or run a command: kvbox connect <name> -- <cmd>)").argument("<name>", "box name").argument("[cmd...]", "command to run instead of a shell").passThroughOptions().action(async (name, cmdArgs, _opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  let ep;
+  let cert;
+  let owner;
+  try {
+    let box = pickRef(await client.listMachines(), name, me(client));
+    if (!box) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
+    cert = await ensureCert(client, void 0, void 0, { owner: box.owner });
+    owner = box.owner;
+    const wasRunning = box.status === "running";
+    if (!wasRunning) box = await wakeUp(client, box, displayName(box, me(client)));
+    ep = sshEndpoint(box, client.target);
+    if (!wasRunning) await spin(`waiting for ${name} to accept SSH\u2026`, waitForSsh(ep));
+  } finally {
+    await client.close();
+  }
+  let res = spawnSync("ssh", [...sshArgs(ep), ...cmdArgs], { stdio: "inherit" });
+  if (res.error) throw new KvboxError(`could not run ssh: ${res.error.message}`);
+  if (res.status === SSH_FAILED) {
+    const again = await clientFor(cmd.optsWithGlobals());
+    const retry = await renewAfterRefusal(again, cert, owner).finally(() => again.close());
+    if (retry) {
+      info("renewed your SSH certificate, trying again\u2026");
+      res = spawnSync("ssh", [...sshArgs(ep), ...cmdArgs], { stdio: "inherit" });
+      if (res.error) throw new KvboxError(`could not run ssh: ${res.error.message}`);
+    }
+  }
+  process.exit(res.status ?? 1);
+});
+
+// src/commands/vm/exec.ts
+import { spawn as spawn2 } from "child_process";
+import { Command as Command3, InvalidArgumentError } from "commander";
+function shellQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function remoteCommand(cmdArgs, env) {
+  const cmd = cmdArgs.join(" ");
+  if (env.length === 0) return cmd;
+  const assignments = env.map((entry) => {
+    const eq = entry.indexOf("=");
+    const key = eq > 0 ? entry.slice(0, eq) : "";
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new KvboxError(`--env ${entry}: expected KEY=VALUE`);
+    return `${key}=${shellQuote(entry.slice(eq + 1))}`;
+  });
+  return `export ${assignments.join(" ")}; ${cmd}`;
+}
+var TIMEOUT_EXIT = 124;
+var SSH_FAILED2 = 255;
+function collect(value, previous) {
+  return [...previous ?? [], value];
+}
+function positiveSeconds(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError("expected a number of seconds > 0");
+  return n;
+}
+async function runSsh(ssh, opts) {
+  const child = spawn2("ssh", ssh, { stdio: ["inherit", opts.json ? "pipe" : "inherit", opts.json ? "pipe" : "inherit"] });
+  const chunks = [];
+  child.stdout?.on("data", (c) => chunks.push(c));
+  child.stderr?.on("data", (c) => chunks.push(c));
+  let timedOut = false;
+  const timer = opts.timeout === void 0 ? void 0 : setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+  }, opts.timeout * 1e3);
+  const status2 = await new Promise((resolve, reject) => {
+    child.once("error", (err) => reject(new KvboxError(`could not run ssh: ${err.message}`)));
+    child.once("close", (code, signal) => {
+      if (timedOut) resolve(TIMEOUT_EXIT);
+      else if (code !== null) resolve(code);
+      else resolve(signal === "SIGINT" ? 130 : 1);
+    });
+  }).finally(() => clearTimeout(timer));
+  return { status: status2, chunks, timedOut };
+}
+var execCommand = new Command3("exec").description("run a command in a box and exit with its status (kvbox exec <name> -- <cmd>)").argument("<name>", "box name").argument("<cmd...>", "command, passed to the box's shell as one string (pipes, &&, cd work)").option("-e, --env <KEY=VALUE>", "set an environment variable for the command (repeatable)", collect).option("--timeout <seconds>", "kill the command after N seconds and exit 124", positiveSeconds).option("--tty", "allocate a pseudo-terminal (for interactive tools like htop)").option("--json", 'capture output and print {"output": "...", "exit_code": N}').action(async (name, cmdArgs, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  let ep;
+  let cert;
+  let owner;
+  try {
+    let box = pickRef(await client.listMachines(), name, me(client));
+    if (!box) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
+    if (box.status === "stopped") throw new KvboxError(`box ${name} is stopped (kvbox start ${name})`);
+    cert = await ensureCert(client, void 0, void 0, { owner: box.owner });
+    owner = box.owner;
+    const wasRunning = box.status === "running";
+    if (!wasRunning) box = await wakeUp(client, box, displayName(box, me(client)));
+    ep = sshEndpoint(box, client.target);
+    if (!wasRunning) await spin(`waiting for ${name} to accept SSH\u2026`, waitForSsh(ep));
+  } finally {
+    await client.close();
+  }
+  const remote = remoteCommand(cmdArgs, opts.env ?? []);
+  const stdinIsTty = process.stdin.isTTY === true;
+  const ssh = [
+    ...opts.tty ? ["-t"] : [],
+    // With a terminal on stdin nothing is sent (the command would otherwise wait on it);
+    // from a pipe or file, stdin is forwarded and its EOF reaches the command.
+    ...stdinIsTty && !opts.tty ? ["-n"] : [],
+    ...sshArgs(ep),
+    // ssh joins everything after the host into the remote command line.
+    remote
+  ];
+  let { status: status2, chunks, timedOut } = await runSsh(ssh, opts);
+  if (status2 === SSH_FAILED2 && !timedOut) {
+    const again = await clientFor(cmd.optsWithGlobals());
+    if (await renewAfterRefusal(again, cert, owner).finally(() => again.close())) {
+      if (opts.json) process.stderr.write(Buffer.concat(chunks));
+      process.stderr.write("renewed your SSH certificate, trying again\u2026\n");
+      ({ status: status2, chunks, timedOut } = await runSsh(ssh, opts));
+    }
+  }
+  if (status2 === SSH_FAILED2 && !timedOut) {
+    if (opts.json) process.stderr.write(Buffer.concat(chunks));
+    throw new KvboxError(`box ${name}: could not run the command over SSH (box still booting?)`, SSH_FAILED2);
+  }
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ output: Buffer.concat(chunks).toString("utf8"), exit_code: status2 }) + "\n");
+  }
+  process.exit(status2);
+});
+
+// src/commands/vm/hibernate.ts
+import { Command as Command4 } from "commander";
+var hibernateCommand = new Command4("hibernate").description("save a box's memory to disk and free its RAM (kvbox wake continues it where it left off)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`hibernating ${name} (saving its memory to disk)\u2026`, client.hibernateMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} box ${name} hibernated (memory saved to disk, RAM freed; kvbox wake ${name} continues it where it left off)`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/ls.ts
+import { Command as Command5, Option as Option2 } from "commander";
+function ownerCell(b, me2) {
+  const slug = slugOf(b.owner);
+  if (slug === me2) return "private";
+  return b.ownerKind === void 0 ? slug : `${slug} ${color.dim(b.ownerKind)}`;
+}
+function addressOf(b) {
+  if (b.ssh !== void 0) return `${b.ssh.host}:${b.ssh.port}`;
+  return b.ip === "" ? "-" : b.ip;
+}
+var lsCommand = new Command5("ls").description("list boxes with status and address (yours and your orgs'; --org <slug> for one org)").addOption(new Option2("-a, --all", "kept for older scripts: the listing covers everything you can see anyway").hideHelp()).option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const boxes = await client.listMachines();
+    if (opts.json) {
+      json(boxes);
+      return;
+    }
+    const org = client.target.kind === "cloud" ? client.target.org : void 0;
+    if (boxes.length === 0) {
+      info(org === void 0 ? "no boxes yet; create one with: kvbox new" : `no boxes in ${org} yet; create one with: kvbox new --org ${org}`);
+      return;
+    }
+    if (org !== void 0) info(`boxes of ${org}`);
+    table(lsRows(boxes, client.target.kind === "cloud" ? { me: client.target.user } : void 0));
+  } finally {
+    await client.close();
+  }
+});
+function lsRows(boxes, cloud) {
+  return boxes.map((b) => ({
+    ...cloud ? { owner: ownerCell(b, cloud.me) } : {},
+    name: boxName(b.name),
+    status: status(b.status),
+    address: addressOf(b),
+    size: b.status === "unknown" ? "-" : `${shape(b.vcpu, b.memMib, b.diskBytes)} ${color.dim(`(${gbShort(b.diskUsedBytes)} used)`)}`,
+    created: age(b.createdAt)
+  }));
+}
+
+// src/commands/vm/pause.ts
+import { Command as Command6 } from "commander";
+var pauseCommand = new Command6("pause").description("freeze a box in place (memory and processes kept, no CPU used; kvbox resume continues it instantly)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`pausing ${name}\u2026`, client.pauseMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} box ${name} is in standby (frozen in place; kvbox resume ${name} continues it)`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/rescale.ts
+import { Command as Command7, Option as Option3 } from "commander";
+var rescaleCommand = new Command7("rescale").description("change a box's vCPUs, memory or disk (e.g. --vcpu 4 --mem 16GB); a running box restarts").argument("<name>", "box name").addOption(new Option3("-s, --size <size>", "a preset to start from").choices(SIZE_NAMES)).option("--vcpu <n>", "number of vCPUs").option("--mem <size>", "memory, e.g. 16GB or 4096MB").option("--disk <size>", "disk size, e.g. 32GB (grow only)").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const req = {
+    ...opts.size !== void 0 ? { size: opts.size } : {},
+    ...opts.vcpu !== void 0 ? { vcpu: parseCount(opts.vcpu) } : {},
+    ...opts.mem !== void 0 ? { memMib: parseSize("--mem", opts.mem) } : {},
+    ...opts.disk !== void 0 ? { diskGib: parseGib("--disk", opts.disk) } : {}
+  };
+  if (Object.keys(req).length === 0) throw new KvboxError("nothing to change: give --size, --vcpu, --mem or --disk");
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const before = pickRef(await client.listMachines(), name, me(client));
+    if (!before) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
+    const box = await spin(`rescaling ${name}\u2026`, client.rescaleMachine(displayName(before, me(client)), req));
+    if (opts.json) {
+      json(box);
+      return;
+    }
+    const same = box.vcpu === before.vcpu && box.memMib === before.memMib && box.diskBytes === before.diskBytes;
+    if (same) {
+      info(`box ${name} already has that shape; nothing changed`);
+      return;
+    }
+    info(`${color.green("\u2713")} ${describe(box)}`);
+    if (before.status === "running") info("  it was restarted: processes that were running are gone, files are intact");
+  } finally {
+    await client.close();
+  }
+});
+function parseCount(text) {
+  const n = Number(text);
+  if (!Number.isInteger(n) || n < 1) throw new KvboxError(`--vcpu ${text}: give a whole number of vCPUs`);
+  return n;
+}
+function parseSize(flag, text) {
+  const mib = parseMib(text);
+  if (mib === void 0) throw new KvboxError(`${flag} ${text}: give a size like 16GB or 4096MB`);
+  return mib;
+}
+function parseGib(flag, text) {
+  const mib = parseSize(flag, text);
+  if (mib % 1024 !== 0) throw new KvboxError(`${flag} ${text}: disk sizes are whole GB`);
+  return mib / 1024;
+}
+
+// src/commands/vm/resume.ts
+import { Command as Command8 } from "commander";
+var resumeCommand = new Command8("resume").description("continue a box that is in standby (kvbox pause)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`resuming ${name}\u2026`, client.resumeMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} box ${name} resumed`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/rm.ts
+import { Command as Command9 } from "commander";
+var rmCommand = new Command9("rm").description("destroy a box (its disk is deleted; snapshots are kept)").argument("<name>", "box name").option("-y, --yes", "do not ask for confirmation").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = pickRef(await client.listMachines(), name, me(client));
+    if (!box) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
+    const ref = displayName(box, me(client));
+    if (!await confirm(`Destroy box ${ref} and its disk?`, opts.yes ?? false)) {
+      info("cancelled");
+      process.exitCode = 1;
+      return;
+    }
+    await spin(`destroying ${ref}\u2026`, client.deleteMachine(ref));
+    info(`${color.green("\u2713")} box ${ref} destroyed`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/start.ts
+import { Command as Command10 } from "commander";
+var startCommand = new Command10("start").description("boot a stopped box again (same name, IP and disk)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`booting ${name}\u2026`, client.startMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} ${describe(box)}`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/stop.ts
+import { Command as Command11 } from "commander";
+var stopCommand = new Command11("stop").description("shut a box down (its disk is kept; start it again with kvbox start)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`shutting ${name} down\u2026`, client.stopMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} box ${name} stopped (disk kept; kvbox start ${name} boots it again)`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/update.ts
+import { Command as Command12 } from "commander";
+var updateCommand = new Command12("update").description("move a box onto the current base image (its files stay; a running box restarts)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const before = pickRef(await client.listMachines(), name, me(client));
+    if (!before) throw new KvboxError(`box ${name}: not found (kvbox ls)`);
+    const box = await spin(`updating ${name}\u2026`, client.updateMachine(displayName(before, me(client))));
+    if (opts.json) {
+      json(box);
+      return;
+    }
+    if (box.base === before.base) {
+      info(`box ${name} is already on base image ${box.base}`);
+    } else {
+      const restarted = before.status === "running" ? " (restarted: processes that were running are gone, files are intact)" : "";
+      info(`${color.green("\u2713")} box ${color.bold(name)} now runs on base image ${box.base} (was ${before.base})${restarted}`);
+    }
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/usage.ts
+import { Command as Command13 } from "commander";
+var usageCommand = new Command13("usage").description("how long a box ran, slept and sat stopped, as vCPU-hours, RAM and disk GiB-hours (and cost, when the host prices them)").argument("<name>", "box name").option("--since <date>", "count from this date instead of the box's creation, e.g. 2026-10-01").option("--json", "print as JSON").action(async (name, opts, cmd) => {
+  let since;
+  if (opts.since !== void 0) {
+    const t = Date.parse(opts.since);
+    if (Number.isNaN(t)) throw new KvboxError(`--since ${opts.since}: not a date; write it like 2026-10-19 or 2026-10-19T08:00:00Z`);
+    since = new Date(t).toISOString();
+  }
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const u = await client.machineUsage(name, since);
+    if (opts.json) json(u);
+    else process.stdout.write(block(u));
+  } finally {
+    await client.close();
+  }
+});
+var day = (iso) => iso.slice(0, 10);
+var SYMBOLS = { EUR: "\u20AC", USD: "$", GBP: "\xA3" };
+function money(amount, currency) {
+  const n = amount.toFixed(2);
+  const sym = SYMBOLS[currency.toUpperCase()];
+  return sym === void 0 ? `${n} ${currency}` : `${sym}${n}`;
+}
+function block(u) {
+  const estimated = u.estimatedStops === 0 ? "" : color.dim(` (${u.estimatedStops} stop time${u.estimatedStops === 1 ? "" : "s"} estimated)`);
+  const rows = [
+    ["name", boxName(u.name)],
+    ["status", status(u.status)],
+    ["window", `${day(u.window.from)} to ${day(u.window.to)}`],
+    ["running", duration(u.seconds.running) + estimated],
+    ["standby", duration(u.seconds.standby)],
+    ["hibernated", duration(u.seconds.hibernated)],
+    ["stopped", duration(u.seconds.stopped)],
+    ["vcpu-h", hours(u.vcpuHours)],
+    ["ram GiB-h", hours(u.ramGibHours)],
+    ["disk GiB-h", hours(u.diskGibHours)]
+  ];
+  if (u.cost !== void 0) rows.push(["cost", `${money(u.cost.amount, u.cost.currency)} ${color.dim("(estimated)")}`]);
+  if (u.historyFrom !== null && u.historyFrom > u.window.from) {
+    rows.push(["history", color.dim(`from ${u.historyFrom.slice(0, 16).replace("T", " ")} UTC; the box is older, but its time before that was not recorded`)]);
+  }
+  const w = Math.max(...rows.map(([k]) => k.length));
+  return rows.map(([k, v]) => `${" ".repeat(w - k.length)}${k}: ${v}`).join("\n") + "\n";
+}
+
+// src/commands/vm/wake.ts
+import { Command as Command14 } from "commander";
+var wakeCommand = new Command14("wake").description("continue a hibernated box where it left off (same name, IP and disk)").argument("<name>", "box name").option("--json", "print the box as JSON").action(async (name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const box = await spin(`waking ${name} (loading its memory from disk)\u2026`, client.wakeMachine(name));
+    if (opts.json) json(box);
+    else info(`${color.green("\u2713")} box ${name} is awake, running where it left off`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/vm/index.ts
+var vmCommand = new Command15("vm").enablePositionalOptions().description("manage boxes (each one is a Firecracker microVM)").addCommand(newCommand).addCommand(lsCommand).addCommand(connectCommand).addCommand(execCommand).addCommand(stopCommand).addCommand(startCommand).addCommand(pauseCommand).addCommand(resumeCommand).addCommand(hibernateCommand).addCommand(wakeCommand).addCommand(updateCommand).addCommand(rescaleCommand).addCommand(usageCommand).addCommand(rmCommand);
+for (const cmd of vmCommand.commands) cmd.option("--org <slug>", "act in this org (- for your personal boxes)");
+var vmAliases = [newCommand, lsCommand, connectCommand, execCommand, stopCommand, startCommand, pauseCommand, resumeCommand, hibernateCommand, wakeCommand, rmCommand];
+
+// src/commands/server/index.ts
+import { Command as Command23 } from "commander";
+
+// src/commands/server/join.ts
+import { Command as Command16 } from "commander";
+
+// src/commands/server/daemon.ts
+import { spawn as spawn3 } from "child_process";
+import { readFile as readFile4 } from "fs/promises";
+import { setTimeout as sleep2 } from "timers/promises";
+async function runningPid(p = paths()) {
+  let pid;
+  try {
+    pid = Number.parseInt(await readFile4(p.serverPid, "utf8"), 10);
+  } catch {
+    return null;
+  }
+  return alive(pid) ? pid : null;
+}
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function stopLocalServer(pid, timeoutMs = 1e4) {
+  process.kill(pid, "SIGTERM");
+  const deadline = Date.now() + timeoutMs;
+  while (alive(pid)) {
+    if (Date.now() > deadline) throw new KvboxError(`kvbox-server (pid ${pid}) did not stop within ${timeoutMs / 1e3}s`);
+    await sleep2(100);
+  }
+}
+async function restartLocalServer(p = paths()) {
+  const pid = await runningPid(p);
+  if (pid !== null) await stopLocalServer(pid);
+  return (await startLocalServer(p)).pid;
+}
+function runKvboxServer(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn3("kvbox-server", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => out += chunk.toString());
+    child.stderr.on("data", (chunk) => err += chunk.toString());
+    child.once("error", (e) => {
+      reject(new KvboxError(e.code === "ENOENT" ? NOT_A_HOST_HINT : `could not run kvbox-server: ${e.message}`));
+    });
+    child.once("close", (code) => {
+      if (code === 0) resolve(out.trimEnd());
+      else reject(new KvboxError(err.trim().replace(/^error: /, "") || `kvbox-server ${args[0] ?? ""} exited with code ${String(code)}`, code === 2 ? 2 : 1));
+    });
+  });
+}
+
+// src/commands/server/join.ts
+var joinCommand = new Command16("join").description("put this machine behind a control plane (needs a one-time token minted there) and restart its server").argument("<control-plane-url>", "the control plane, e.g. https://api.kvbox.sh").requiredOption("--token <token>", "one-time join token from the control plane").option("--advertise <host-or-ip>", "address the control plane reaches this machine at (default: its default-route address)").option("--name <name>", "how the control plane lists this machine (default: hostname)").action(async (url, opts) => {
+  const args = ["join", url, "--token", opts.token];
+  if (opts.advertise !== void 0) args.push("--advertise", opts.advertise);
+  if (opts.name !== void 0) args.push("--name", opts.name);
+  for (const line of (await runKvboxServer(args)).split("\n")) info(line);
+  const pid = await spin("restarting kvbox-server\u2026", restartLocalServer(paths()));
+  info(`kvbox-server restarted (pid ${pid}); it answers the control plane now`);
+});
+
+// src/commands/server/leave.ts
+import { Command as Command17 } from "commander";
+var leaveCommand = new Command17("leave").description("take this machine out from behind its control plane and restart its server").action(async () => {
+  const p = paths();
+  for (const line of (await runKvboxServer(["leave"])).split("\n")) info(line);
+  if (await runningPid(p) === null) return;
+  const pid = await spin("restarting kvbox-server\u2026", restartLocalServer(p));
+  info(`kvbox-server restarted (pid ${pid}); only this machine talks to it now`);
+});
+
+// src/commands/server/relay.ts
+import { Command as Command18 } from "commander";
+var relayCommand = new Command18("relay").description("reach the internet through a relay (paste what `kvbox-relay add` printed on the relay VM); `off` takes the tunnel down").argument("<join-string>", "the line `kvbox-relay add` printed, or `off`").action(async (joinString) => {
+  for (const line of (await runKvboxServer(["relay", joinString])).split("\n")) info(line);
+});
+
+// src/commands/server/start.ts
+import { Command as Command19 } from "commander";
+var startCommand2 = new Command19("start").description("start the local kvbox-server in the background").action(async (_opts, cmd) => {
+  const client = await clientFor({ ...cmd.optsWithGlobals(), local: true }, { autoStart: false });
+  try {
+    const health = await client.health();
+    info(`kvbox-server ${health.version} is already running (pid ${health.pid})`);
+    return;
+  } catch {
+  } finally {
+    await client.close();
+  }
+  const { pid, socketPath, viaGroup } = await startLocalServer(paths());
+  info(`kvbox-server started (pid ${pid}), listening on ${socketPath}`);
+  if (viaGroup !== void 0) info(`started through the ${viaGroup} group, which this shell does not have yet (log out and back in to get it)`);
+});
+
+// src/commands/server/status.ts
+import { Command as Command20 } from "commander";
+var statusCommand = new Command20("status").description("show whether this machine's server is running, its control plane and which base image new boxes get").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor({ ...cmd.optsWithGlobals(), local: true });
+  try {
+    const health = await client.health();
+    if (opts.json) json(health);
+    else {
+      info(`kvbox-server ${health.version} running, pid ${health.pid}`);
+      if (health.controlPlane) info(`control plane: ${health.controlPlane.name} at ${health.controlPlane.url}, this host answers it on ${health.controlPlane.hostUrl}`);
+      else info("control plane: none (kvbox server join <url> --token <token> puts this machine behind one)");
+      if (health.relay) info(`relay: ${health.relay.name} lends this machine ${health.relay.publicIp} (tunnel to ${health.relay.endpoint})`);
+      if (health.base === null) info("base image: none usable yet (run install-server.sh)");
+      else info(`base image: ${health.base} (what kvbox new uses; kvbox vm update <box> moves an older box onto it)`);
+    }
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/server/stop.ts
+import { Command as Command21 } from "commander";
+var stopCommand2 = new Command21("stop").description("stop the local server (running boxes are not affected)").action(async () => {
+  const pid = await runningPid(paths());
+  if (pid === null) throw new KvboxError("kvbox-server is not running");
+  await stopLocalServer(pid);
+  info(`kvbox-server stopped (pid ${pid})`);
+});
+
+// src/commands/server/trust-ca.ts
+import { Command as Command22 } from "commander";
+var trustCaCommand = new Command22("trust-ca").description("make every cloud box on this machine trust a new SSH CA (after `ca rotate` on the control plane)").argument("[public-key]", "the CA public key (or its cert-authority line); or --from-cloud").option("--from-cloud", "ask the control plane this host joined for its current CA, show the fingerprint, then ask").option("-y, --yes", "do not ask for confirmation").option("--json", "print the report as JSON").action(async (publicKey, opts, cmd) => {
+  if (publicKey === void 0 && !opts.fromCloud) throw new KvboxError("give the CA public key, or --from-cloud to fetch it from the control plane this host joined");
+  if (publicKey !== void 0 && opts.fromCloud) throw new KvboxError("either a public key or --from-cloud, not both");
+  const client = await clientFor({ ...cmd.optsWithGlobals(), local: true });
+  try {
+    let key = publicKey;
+    if (key === void 0) {
+      const ca = await client.cloudCa();
+      info(`${ca.controlPlane} says its SSH CA is ${ca.fingerprint}`);
+      if (!await confirm(`make every cloud box on this machine trust it (in place of the CA it trusts now)?`, opts.yes ?? false)) {
+        throw new KvboxError("cancelled", 130);
+      }
+      key = ca.publicKey;
+    }
+    const report = await client.trustCa({ publicKey: key });
+    if (opts.json) json(report);
+    else describeReport(report);
+  } finally {
+    await client.close();
+  }
+});
+var WHEN = {
+  start: "is stopped: it trusts the CA from its next start",
+  wake: "is hibernated: it trusts the CA from its next wake",
+  resume: "is in standby: it trusts the CA from its next resume",
+  later: "is running but could not take it now; it trusts the CA from its next stop and start"
+};
+function describeReport(report) {
+  info(`CA ${report.fingerprint}`);
+  for (const box of report.updated) info(`box ${box} now trusts the CA`);
+  for (const p of report.pending) info(`box ${p.box} ${WHEN[p.when]}${p.why ? ` (${p.why})` : ""}`);
+  for (const f of report.failed) warn(`box ${f.box}: ${f.error}`);
+  const parts = [`${report.updated.length} box(es) updated now`, `${report.pending.length} pending`, `${report.failed.length} failed`];
+  if (report.local > 0) parts.push(`${report.local} local box(es) untouched (they trust this host's key only)`);
+  info(parts.join(", "));
+}
+
+// src/commands/server/index.ts
+var serverCommand = new Command23("server").description("run or manage the kvbox server").addCommand(startCommand2).addCommand(statusCommand).addCommand(stopCommand2).addCommand(joinCommand).addCommand(leaveCommand).addCommand(relayCommand).addCommand(trustCaCommand);
+
+// src/commands/login.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import { hostname as osHostname } from "os";
+import { createInterface } from "readline/promises";
+import { Writable } from "stream";
+import { Command as Command24 } from "commander";
+var loginCommand = new Command24("login").description("log in to the kvbox cloud (or your own control plane) and target it from now on").argument("[url]", `control plane URL (default: ${DEFAULT_CLOUD_URL})`).option("-e, --email <email>", "account email (prompted otherwise)").option("--password-stdin", "read the password from the first line of stdin (for scripts)").action(async (urlArg, opts) => {
+  const url = normalizeUrl(urlArg ?? DEFAULT_CLOUD_URL);
+  const creds = await readCredentials(opts);
+  const session = await runLogin(url, creds, paths());
+  info(`logged in to ${hostOf(url)} as ${session.user}`);
+});
+async function readCredentials(opts, io = { stdin: process.stdin, isTTY: process.stdin.isTTY === true }) {
+  const noTerminal = () => new KvboxError("stdin is not a terminal: pass --email and --password-stdin");
+  let email = opts.email;
+  if (email === void 0) {
+    if (!io.isTTY) throw noTerminal();
+    email = await prompt("email: ", { input: process.stdin, output: process.stderr });
+  }
+  let password;
+  if (opts.passwordStdin) password = await firstLine(io.stdin);
+  else if (io.isTTY) password = await promptSecret("password: ", { input: process.stdin, output: process.stderr });
+  else throw noTerminal();
+  if (email === "") throw new KvboxError("email is empty");
+  if (password === "") throw new KvboxError("password is empty");
+  return { email, password };
+}
+async function runLogin(url, creds, p = paths(), hostname = osHostname()) {
+  const publicKey = await ensureSshKey(p, hostname);
+  const client = new ServerClient({ kind: "cloud", url, token: "" }, { autoStart: false });
+  let res;
+  try {
+    res = await client.login({ email: creds.email, password: creds.password, publicKey });
+  } finally {
+    await client.close();
+  }
+  const session = { url, token: res.token, user: res.user.username };
+  if (res.sshCert !== void 0 && res.sshCertExpires !== void 0) {
+    await writeCert(res.sshCert, p);
+    session.sshCertExpires = res.sshCertExpires;
+    if (res.sshCertPrincipals !== void 0) session.sshCertPrincipals = res.sshCertPrincipals;
+  }
+  await writeSession(session, p);
+  return session;
+}
+async function ensureSshKey(p = paths(), hostname = osHostname()) {
+  const pubPath = `${p.sshKey}.pub`;
+  const pub = await readFile5(pubPath, "utf8").catch(() => null);
+  if (pub !== null) return pub.trim();
+  await mkdir3(p.ssh, { recursive: true, mode: 448 });
+  const havePrivate = await readFile5(p.sshKey).then(() => true, () => false);
+  const args = havePrivate ? ["-y", "-f", p.sshKey] : ["-q", "-t", "ed25519", "-N", "", "-C", `kvbox@${hostname}`, "-f", p.sshKey];
+  const res = spawnSync2("ssh-keygen", args, { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+  if (res.error) {
+    if (res.error.code === "ENOENT") throw new KvboxError("ssh-keygen not found; install OpenSSH");
+    throw new KvboxError(`could not run ssh-keygen: ${res.error.message}`);
+  }
+  if (res.status !== 0) throw new KvboxError(`ssh-keygen failed: ${res.stderr.trim()}`);
+  if (havePrivate) await writeFile3(pubPath, res.stdout.trim() + "\n");
+  return (await readFile5(pubPath, "utf8")).trim();
+}
+async function prompt(question, io) {
+  const rl = createInterface({ input: io.input, output: io.output });
+  return (await ask(rl, question)).trim();
+}
+async function promptSecret(question, io) {
+  const sink = new Writable({ write: (_chunk, _enc, cb) => cb() });
+  const rl = createInterface({ input: io.input, output: sink, terminal: true });
+  io.output.write(question);
+  try {
+    return await ask(rl, question);
+  } finally {
+    io.output.write("\n");
+  }
+}
+async function ask(rl, question) {
+  let onClose = () => {
+  };
+  const closed = new Promise((_, reject) => {
+    onClose = () => reject(new KvboxError("cancelled", 130));
+    rl.once("close", onClose);
+  });
+  try {
+    return await Promise.race([rl.question(question).catch(cancelled), closed]);
+  } finally {
+    rl.off("close", onClose);
+    rl.close();
+  }
+}
+function cancelled(err) {
+  if (err.code === "ABORT_ERR") throw new KvboxError("cancelled", 130);
+  throw err;
+}
+async function firstLine(stream) {
+  const rl = createInterface({ input: stream });
+  try {
+    for await (const line of rl) return line.trim();
+    return "";
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/logout.ts
+import { Command as Command25 } from "commander";
+var logoutCommand = new Command25("logout").description("log out of the control plane; commands target this machine's kvbox-server again").action(async () => {
+  const p = paths();
+  const session = await readSession(p).catch(() => null);
+  switch (await runLogout(p)) {
+    case "none":
+      info("not logged in");
+      break;
+    case "unreadable":
+      info(`logged out (${p.cli} was unreadable and is gone)`);
+      break;
+    case "cleared":
+      info(`logged out of ${hostOf(session?.url ?? "")}`);
+  }
+});
+async function runLogout(p = paths()) {
+  let session;
+  try {
+    session = await readSession(p);
+  } catch {
+    await clearSession(p);
+    await removeCert(p);
+    return "unreadable";
+  }
+  if (!session) return "none";
+  const client = new ServerClient({ kind: "cloud", url: session.url, token: session.token }, { autoStart: false });
+  try {
+    await client.logout();
+  } catch {
+  } finally {
+    await client.close();
+  }
+  await clearSession(p);
+  await removeCert(p);
+  return "cleared";
+}
+
+// src/commands/whoami.ts
+import { Command as Command26 } from "commander";
+var whoamiCommand = new Command26("whoami").description("show which account and control plane commands target (or local mode)").option("--json", "print as JSON").action(async (opts) => {
+  const session = await readSession();
+  if (opts.json) {
+    json(session ? { user: session.user, url: session.url, sshCertExpires: session.sshCertExpires ?? null } : null);
+    return;
+  }
+  process.stdout.write(describeSession(session) + "\n");
+});
+function describeSession(session) {
+  if (!session) return "not logged in (local mode)";
+  const lines = [`${session.user} on ${hostOf(session.url)}`];
+  if (session.sshCertExpires) lines.push(`certificate valid until ${session.sshCertExpires.slice(0, 10)}`);
+  return lines.join("\n");
+}
+
+// src/commands/snapshots/index.ts
+import { Command as Command30 } from "commander";
+
+// src/commands/snapshots/ls.ts
+import { Command as Command27, Option as Option4 } from "commander";
+var lsCommand2 = new Command27("ls").description("list snapshots (yours and your orgs'; --org <slug> for one org)").addOption(new Option4("-a, --all", "kept for older scripts: the listing covers everything you can see anyway").hideHelp()).option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const cloud = client.target.kind === "cloud";
+    const snaps = await client.listSnapshots();
+    if (opts.json) {
+      json(snaps);
+      return;
+    }
+    if (snaps.length === 0) {
+      info("no snapshots yet; freeze a running box with: kvbox snapshots new <box> <name>");
+      return;
+    }
+    const org = client.target.kind === "cloud" ? client.target.org : void 0;
+    if (org !== void 0) info(`snapshots of ${org}`);
+    table(
+      snaps.map((s) => ({
+        ...cloud ? { owner: slugOf(s.owner) === client.target.user ? "private" : slugOf(s.owner) } : {},
+        name: boxName(s.name),
+        "from box": shortRef(s.source, s.owner),
+        shape: shape(s.vcpu, s.memMib),
+        "on disk": gbShort(s.sizeBytes),
+        created: age(s.createdAt)
+      }))
+    );
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/snapshots/new.ts
+import { Command as Command28 } from "commander";
+var newCommand2 = new Command28("new").description("freeze a running box (memory + disk) into a snapshot; the box keeps running").argument("<box>", "box name").argument("<name>", "snapshot name").option("--json", "print the snapshot as JSON").action(async (box, name, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    const snap = await spin(`saving snapshot ${name} from box ${box} (memory + disk)\u2026`, client.createSnapshot({ box, name }));
+    if (opts.json) json(snap);
+    else info(`${color.green("\u2713")} snapshot ${name} saved from box ${box} (${gb(snap.sizeBytes)} on disk); start a warm clone with: kvbox new --from ${name}`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/snapshots/rm.ts
+import { Command as Command29 } from "commander";
+var rmCommand2 = new Command29("rm").description("delete a snapshot (boxes made from it are not affected)").argument("<name>", "snapshot name").option("-y, --yes", "do not ask for confirmation").action(async (name, opts, cmd) => {
+  if (!await confirm(`Delete snapshot ${name}?`, opts.yes ?? false)) {
+    info("cancelled");
+    process.exitCode = 1;
+    return;
+  }
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    await spin(`deleting snapshot ${name}\u2026`, client.deleteSnapshot(name));
+    info(`${color.green("\u2713")} snapshot ${name} deleted`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/snapshots/index.ts
+var snapshotsCommand = new Command30("snapshots").aliases(["snapshot", "snap"]).description("freeze running boxes into snapshots and manage them").addCommand(newCommand2).addCommand(lsCommand2).addCommand(rmCommand2);
+for (const cmd of snapshotsCommand.commands) cmd.option("--org <slug>", "act in this org (- for your personal boxes)");
+
+// src/commands/org/index.ts
+import { Command as Command36 } from "commander";
+
+// src/commands/org/ls.ts
+import { Command as Command31 } from "commander";
+
+// src/commands/org/context.ts
+var NOT_LOGGED_IN = "orgs live on the control plane: kvbox login first";
+async function cloudClientFor(opts) {
+  const client = await clientFor(opts, { autoStart: false });
+  if (client.target.kind === "local") {
+    await client.close();
+    throw new KvboxError(NOT_LOGGED_IN);
+  }
+  return client;
+}
+function orgFor(opts, target) {
+  if (target.kind === "local") throw new KvboxError(NOT_LOGGED_IN);
+  const slug = opts.org ?? target.org;
+  if (slug === void 0) throw new KvboxError("no org: pass --org <slug>");
+  return slug;
+}
+
+// src/commands/org/ls.ts
+var lsCommand3 = new Command31("ls").description("list the orgs you belong to and your role in each").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const orgs = await client.listOrgs();
+    if (opts.json) {
+      json(orgs);
+      return;
+    }
+    if (orgs.length === 0) {
+      info("you are in no org yet; make one with: kvbox org new <slug>");
+      return;
+    }
+    table(orgRows(orgs));
+  } finally {
+    await client.close();
+  }
+});
+function orgRows(orgs) {
+  return orgs.map((o) => ({ org: boxName(o.slug), name: o.name, role: o.role, since: age(o.createdAt) }));
+}
+
+// src/commands/org/members.ts
+import { Command as Command32, Option as Option5 } from "commander";
+var lsCommand4 = new Command32("ls").description("list an org's members and their roles").option("-o, --org <slug>", "the org (or --org before the command)").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const org = await client.getOrg(orgFor(opts, client.target));
+    if (opts.json) {
+      json(org.members);
+      return;
+    }
+    info(`${org.slug} (${org.name})`);
+    table(org.members.map((m) => ({ user: boxName(m.username), name: m.name, role: m.role, since: age(m.addedAt) })));
+  } finally {
+    await client.close();
+  }
+});
+var addCommand = new Command32("add").description("add a user to an org (admins and owners; only an owner can add an owner)").argument("<user>", "their username").addOption(new Option5("-r, --role <role>", "their role").choices(ORG_ROLES).default("member")).option("-o, --org <slug>", "the org (or --org before the command)").action(async (user, opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const slug = orgFor(opts, client.target);
+    await client.addMember(slug, { username: user, role: opts.role });
+    info(`${color.green("\u2713")} ${user} is now a ${opts.role} of ${slug}`);
+  } finally {
+    await client.close();
+  }
+});
+var rmCommand3 = new Command32("rm").description("remove a member (or leave: remove yourself)").argument("<user>", "their username").option("-o, --org <slug>", "the org (or --org before the command)").option("-y, --yes", "do not ask for confirmation").action(async (user, opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const slug = orgFor(opts, client.target);
+    if (!await confirm(`Remove ${user} from ${slug}?`, opts.yes ?? false)) {
+      info("cancelled");
+      process.exitCode = 1;
+      return;
+    }
+    const self = client.target.kind === "cloud" && client.target.user === user;
+    await client.removeMember(slug, user);
+    info(`${color.green("\u2713")} ${self ? `you left ${slug}` : `${user} removed from ${slug}`}`);
+  } finally {
+    await client.close();
+  }
+});
+var membersCommand = new Command32("members").description("who is in an org and what they may do").addCommand(lsCommand4).addCommand(addCommand).addCommand(rmCommand3);
+
+// src/commands/org/new.ts
+import { Command as Command33 } from "commander";
+var newCommand3 = new Command33("new").description("create an org; you become its owner (the slug is permanent, the name is not)").argument("<slug>", "the org's slug: lowercase, like a username (acme)").option("-n, --name <name>", "display name (default: the slug)").option("--json", "print the org as JSON").action(async (slug, opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const org = await client.createOrg({ slug, name: opts.name ?? slug });
+    if (opts.json) {
+      json(org);
+      return;
+    }
+    info(`${color.green("\u2713")} org ${color.bold(org.slug)} created (${org.name}); you are its owner`);
+    info(`  work in it with: kvbox org use ${org.slug}   (then bare box names are ${org.slug}'s)`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/org/rm.ts
+import { Command as Command34 } from "commander";
+var rmCommand4 = new Command34("rm").description("delete an org (owners only; remove its boxes and snapshots first)").argument("<slug>", "the org").option("-y, --yes", "do not ask for confirmation").action(async (slug, opts, cmd) => {
+  if (!await confirm(`Delete org ${slug}? Its members lose access; its slug stays taken.`, opts.yes ?? false)) {
+    info("cancelled");
+    process.exitCode = 1;
+    return;
+  }
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    await client.deleteOrg(slug);
+    info(`${color.green("\u2713")} org ${slug} deleted`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/org/role.ts
+import { Argument, Command as Command35 } from "commander";
+var roleCommand = new Command35("role").description("change a member's role (owners only)").argument("<user>", "their username").addArgument(new Argument("<role>", "owner, admin or member").choices(ORG_ROLES)).option("-o, --org <slug>", "the org (default: the current context)").action(async (user, role, opts, cmd) => {
+  const client = await cloudClientFor(cmd.optsWithGlobals());
+  try {
+    const slug = orgFor(opts, client.target);
+    await client.setRole(slug, user, role);
+    info(`${color.green("\u2713")} ${user} is now a ${role} of ${slug}`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/org/index.ts
+var orgCommand = new Command36("org").description("orgs: shared slugs that own boxes, with owners, admins and members").addCommand(lsCommand3).addCommand(newCommand3).addCommand(membersCommand).addCommand(roleCommand).addCommand(rmCommand4);
+
+// src/commands/usage.ts
+import { Command as Command37 } from "commander";
+var usageCommand2 = new Command37("usage").description("what your boxes used this month (or --since/--until): running time, vCPU-h, RAM and disk GiB-h, cost").option("--since <date>", "count from this date, e.g. 2026-10-01 (default: the 1st of this month)").option("--until <date>", "count up to this date (default: now)").option("--org <slug>", "one org's boxes only").option("--json", "print as JSON").action(async (opts, cmd) => {
+  for (const [name, value] of [
+    ["since", opts.since],
+    ["until", opts.until]
+  ]) {
+    if (value !== void 0 && Number.isNaN(Date.parse(value))) throw new KvboxError(`--${name} ${value}: not a date; write it like 2026-10-19 or 2026-10-19T08:00:00Z`);
+  }
+  const client = await clientFor(cmd.optsWithGlobals());
+  try {
+    if (client.target.kind === "local" && cmd.optsWithGlobals().org) throw new KvboxError("--org needs a control plane: kvbox login, or drop --org");
+    const report = await client.usageReport(opts.since, opts.until);
+    if (opts.json) {
+      json(report);
+      return;
+    }
+    const cloud = client.target.kind === "cloud" ? { me: client.target.user } : void 0;
+    info(`${day2(report.window.from)} to ${day2(report.window.to)}`);
+    if (report.boxes.length === 0) {
+      info("no usage in this window");
+      return;
+    }
+    table(usageRows(report, cloud));
+  } finally {
+    await client.close();
+  }
+});
+var day2 = (iso) => iso.slice(0, 10);
+function ownerCell2(b, me2) {
+  const slug = slugOf(b.owner);
+  if (slug === me2) return "private";
+  return b.ownerKind === void 0 ? slug : `${slug} ${color.dim(b.ownerKind)}`;
+}
+function usageRows(report, cloud) {
+  const priced = report.totals.cost !== void 0;
+  const rows = report.boxes.map((b) => ({
+    ...cloud ? { owner: ownerCell2(b, cloud.me) } : {},
+    name: boxName(b.name),
+    status: b.status === "removed" ? color.dim("removed") : status(b.status),
+    running: duration(b.seconds.running),
+    "vcpu-h": hours(b.vcpuHours),
+    "ram GiB-h": hours(b.ramGibHours),
+    "disk GiB-h": hours(b.diskGibHours),
+    ...priced ? { cost: money(b.cost?.amount ?? 0, report.totals.cost.currency) } : {}
+  }));
+  const t = report.totals;
+  rows.push({
+    ...cloud ? { owner: "" } : {},
+    name: color.bold("total"),
+    status: "",
+    running: duration(t.seconds.running),
+    "vcpu-h": hours(t.vcpuHours),
+    "ram GiB-h": hours(t.ramGibHours),
+    "disk GiB-h": hours(t.diskGibHours),
+    ...priced ? { cost: `${money(t.cost.amount, t.cost.currency)} ${color.dim("(estimated)")}` } : {}
+  });
+  return rows;
+}
+
+// src/program.ts
+function buildProgram() {
+  const program = new Command38("kvbox").description("self-hosted Firecracker microVMs with Docker-like ergonomics").version(VERSION, "-v, --version").option("--local", "use this machine's kvbox-server over its socket, ignoring kvbox login").option("--org <slug>", "the org: where kvbox new creates, and which box a name means when it is not one of yours; before the command here, or after it").showHelpAfterError().enablePositionalOptions();
+  program.addCommand(vmCommand);
+  program.addCommand(snapshotsCommand);
+  program.addCommand(serverCommand);
+  program.addCommand(loginCommand);
+  program.addCommand(logoutCommand);
+  program.addCommand(whoamiCommand);
+  program.addCommand(orgCommand);
+  program.addCommand(usageCommand2);
+  for (const cmd of vmAliases) program.addCommand(cmd);
+  return program;
+}
+
+// src/index.ts
+try {
+  await buildProgram().parseAsync(process.argv);
+} catch (err) {
+  if (err instanceof KvboxError) {
+    process.stderr.write(color.red(`error: ${err.message}`) + "\n");
+    process.exit(err.exitCode);
+  }
+  throw err;
+}
+//# sourceMappingURL=kvbox.js.map