@kvbox/cli 0.5.5 → 0.5.7

package/dist/kvbox.js

@@ -81,11 +81,11 @@ function age(iso, now = Date.now()) {
   if (min < 60) return `${min}m ago`;
   const hr = Math.floor(min / 60);
   if (hr < 24) return `${hr}h ago`;
-  const day2 = Math.floor(hr / 24);
-  if (day2 < 30) return `${day2}d ago`;
-  const month = Math.floor(day2 / 30);
+  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(day2 / 365)}y ago`;
+  return `${Math.floor(day3 / 365)}y ago`;
 }
 function duration(seconds) {
   const s = Math.max(0, Math.round(seconds));
@@ -147,7 +147,7 @@ async function spin(message, work, opts = {}) {
 }
 
 // src/program.ts
-import { Command as Command37 } from "commander";
+import { Command as Command38 } from "commander";
 
 // ../shared/src/version.ts
 import { createRequire } from "module";
@@ -162,7 +162,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.5.5" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.5.7" : void 0);
 
 // src/commands/vm/index.ts
 import { Command as Command15 } from "commander";
@@ -510,10 +510,48 @@ var MachineUsageSchema = z2.object({
   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 ACTIVATED_BY = ["card", "admin"];
+var ActivatedBySchema = z2.enum(ACTIVATED_BY);
 var CloudUserSchema = z2.object({
   /** The handle: what hosts file boxes under (`<username>@<control plane>`). Lowercase, no `@` or `/`. */
   username: z2.string(),
@@ -522,7 +560,14 @@ var CloudUserSchema = z2.object({
   /** Login identity, unique. */
   email: z2.string(),
   role: z2.enum(["admin", "user"]),
-  createdAt: z2.string()
+  createdAt: z2.string(),
+  /**
+   * False until a card is on file or an admin activates the account (#74): then only `/me` and
+   * `/logout` answer. Admins are never gated. A control plane older than #74 does not send these and
+   * gates nobody, hence the defaults: a newer CLI must still parse its answers.
+   */
+  active: z2.boolean().default(true),
+  activatedBy: ActivatedBySchema.nullable().default(null)
 });
 var ORG_ROLES = ["owner", "admin", "member"];
 var OrgRoleSchema = z2.enum(ORG_ROLES);
@@ -530,7 +575,10 @@ var CloudOrgSchema = z2.object({
   slug: z2.string(),
   /** Display name; the slug never changes, this may. */
   name: z2.string(),
-  createdAt: z2.string()
+  createdAt: z2.string(),
+  /** An org pays for itself (#74): off until it has a card or an admin activates it; its boxes are 402. Defaults as on CloudUser. */
+  active: z2.boolean().default(true),
+  activatedBy: ActivatedBySchema.nullable().default(null)
 });
 var OrgMembershipSchema = CloudOrgSchema.extend({ role: OrgRoleSchema });
 var OrgMemberSchema = z2.object({
@@ -551,6 +599,32 @@ var AddMemberRequestSchema = z2.object({
 });
 var SetRoleRequestSchema = z2.object({ role: OrgRoleSchema });
 var MeResponseSchema = CloudUserSchema.extend({ orgs: z2.array(OrgMembershipSchema) });
+var BalanceSchema = z2.object({
+  slug: z2.string(),
+  balance: z2.number(),
+  currency: z2.string(),
+  topUps: z2.number(),
+  spent: z2.number(),
+  /** The first moment usage counts from: the slug's first top-up; null when it has none. */
+  since: z2.string().nullable(),
+  /** When the slug ran out and its boxes were hibernated (the `sweep-credit` job); null in good standing. Absent from a control plane older than this field. */
+  suspendedAt: z2.string().nullable().default(null)
+});
+var TopUpRequestSchema = z2.object({
+  slug: z2.string().min(1),
+  /** In the control plane's currency; negative corrects a mistake. */
+  amount: z2.number().finite(),
+  note: z2.string().max(200).optional()
+});
+var TopUpSchema = z2.object({
+  id: z2.string(),
+  slug: z2.string(),
+  amount: z2.number(),
+  currency: z2.string(),
+  source: z2.enum(["admin", "card", "trial"]),
+  note: z2.string().nullable(),
+  at: z2.string()
+});
 var LoginRequestSchema = z2.object({
   email: z2.string().min(1),
   password: z2.string().min(1),
@@ -784,6 +858,18 @@ var ServerClient = class {
     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);
+  }
+  /** The prepaid balance of the caller's slug, or of `--org`'s (#76); a control plane only. */
+  balance() {
+    return this.call("GET", "/billing/balance", BalanceSchema);
+  }
   deleteMachine(name) {
     return this.call("DELETE", `/machines/${encodeURIComponent(name)}`, z3.undefined());
   }
@@ -1343,9 +1429,10 @@ var usageCommand = new Command13("usage").description("how long a box ran, slept
 var day = (iso) => iso.slice(0, 10);
 var SYMBOLS = { EUR: "\u20AC", USD: "$", GBP: "\xA3" };
 function money(amount, currency) {
-  const n = amount.toFixed(2);
+  const sign = amount < 0 ? "-" : "";
+  const n = Math.abs(amount).toFixed(2);
   const sym = SYMBOLS[currency.toUpperCase()];
-  return sym === void 0 ? `${n} ${currency}` : `${sym}${n}`;
+  return sym === void 0 ? `${sign}${n} ${currency}` : `${sign}${sym}${n}`;
 }
 function block(u) {
   const estimated = u.estimatedStops === 0 ? "" : color.dim(` (${u.estimatedStops} stop time${u.estimatedStops === 1 ? "" : "s"} estimated)`);
@@ -1925,9 +2012,83 @@ var roleCommand = new Command35("role").description("change a member's role (own
 // 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");
+    else table(usageRows(report, cloud));
+    if (cloud) {
+      const line = await creditLine(client, cloud.me);
+      if (line !== void 0) info(line);
+    }
+  } finally {
+    await client.close();
+  }
+});
+var day2 = (iso) => iso.slice(0, 10);
+async function creditLine(client, me2) {
+  let b;
+  try {
+    b = await client.balance();
+  } catch (err) {
+    if (err instanceof KvboxError) return void 0;
+    throw err;
+  }
+  const whose = b.slug === me2 ? "private" : b.slug;
+  const left = money(b.balance, b.currency);
+  const line = `credit: ${b.balance > 0 ? left : color.red(left)} left ${color.dim(`(${whose})`)}`;
+  return b.suspendedAt ? `${line} ${color.red("out of credit: boxes hibernated until you top up")}` : line;
+}
+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 Command37("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();
+  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);
@@ -1935,6 +2096,7 @@ function buildProgram() {
   program.addCommand(logoutCommand);
   program.addCommand(whoamiCommand);
   program.addCommand(orgCommand);
+  program.addCommand(usageCommand2);
   for (const cmd of vmAliases) program.addCommand(cmd);
   return program;
 }