@kvbox/cli 0.5.23 → 0.5.25

package/README.md

@@ -0,0 +1,19 @@
+# @kvbox/cli
+
+The `kvbox` command: Firecracker microVMs with Docker-like ergonomics. Every box is a real VM with its own kernel, boots in seconds, and can be snapshotted warm and cloned.
+
+```
+npm i -g @kvbox/cli
+kvbox login                    # use kvbox.sh, or point it at your own host
+kvbox new dev --size m         # boot a box
+kvbox connect dev              # shell in over SSH
+kvbox exec dev -- uname -a
+kvbox snapshots new dev base   # memory + disk, the box keeps running
+kvbox new api --from base      # a warm clone
+kvbox volume create data --size 50GB --box dev   # a disk that outlives the box, at /mnt/data
+kvbox ls / kvbox rm dev
+```
+
+This is a thin client, any OS. It talks to [kvbox.sh](https://kvbox.sh) or to a host of your own running [`@kvbox/server`](https://www.npmjs.com/package/@kvbox/server). Every listing command takes `--json`.
+
+Docs: [kvbox.sh/docs](https://kvbox.sh/docs). Agent skill: [kvbox.sh/kvbox/SKILL.md](https://kvbox.sh/kvbox/SKILL.md).

package/dist/kvbox.js

@@ -149,7 +149,7 @@ async function spin(message, work, opts = {}) {
 }
 
 // src/program.ts
-import { Command as Command57 } from "commander";
+import { Command as Command61 } from "commander";
 
 // ../shared/src/version.ts
 import { createRequire } from "module";
@@ -164,7 +164,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.5.23" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.5.25" : void 0);
 
 // src/commands/vm/index.ts
 import { Command as Command26 } from "commander";
@@ -262,6 +262,9 @@ function paths(home = kvboxHome()) {
         disk: join(dir, "disk.ext4")
       };
     },
+    /** Each owner's environment variables as the control plane last sent them (#88): env/<owner>.json, mode 600. */
+    env: join(home, "env"),
+    ownerEnv: (owner) => join(home, "env", `${owner}.json`),
     snapshot: (owner, name) => {
       const dir = join(home, "snapshots", owner, name);
       return {
@@ -496,15 +499,35 @@ var CreateVolumeRequest = z2.object({
   name: z2.string(),
   sizeGib: z2.number().int().min(1).max(MAX_VOLUME_GIB),
   /**
-   * Through a control plane (#91): the box this volume is for, so it is made on that box's host. A
-   * volume attaches only to a box on its own host. Absent: the host with the most room for volumes.
-   * A host ignores it.
+   * Through a control plane (#91): the box this volume is for, so it is made on that box's host; the
+   * control plane requires it (a volume attaches only to a box on its own host, so one made for no box
+   * could never attach) and the CLI attaches right after. A host ignores it.
    */
   box: z2.string().optional()
 });
 var AttachVolumeRequest = z2.object({
   box: z2.string()
 });
+var EnvVarSchema = z2.object({
+  name: z2.string(),
+  value: z2.string().optional(),
+  secret: z2.boolean(),
+  updatedAt: z2.string()
+});
+var SetEnvRequest = z2.object({
+  value: z2.string(),
+  secret: z2.boolean().optional()
+});
+var EnvChangeSchema = z2.object({
+  owner: z2.string(),
+  name: z2.string(),
+  boxes: z2.number().int()
+});
+var HostEnvRequest = z2.object({
+  version: z2.number().int().min(0),
+  vars: z2.array(z2.object({ name: z2.string(), value: z2.string() }))
+});
+var HostEnvVersionsSchema = z2.array(z2.object({ owner: z2.string(), version: z2.number().int() }));
 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. */
@@ -1137,6 +1160,16 @@ var ServerClient = class {
   deleteSnapshot(name) {
     return this.call("DELETE", `/snapshots/${encodeURIComponent(name)}`, z3.undefined());
   }
+  // ---- environment variables (#88), a control plane only: the caller's slug, or `--org`'s ----
+  listEnv() {
+    return this.call("GET", "/env", z3.array(EnvVarSchema));
+  }
+  setEnv(name, req) {
+    return this.call("PUT", `/env/${encodeURIComponent(name)}`, EnvChangeSchema, req);
+  }
+  removeEnv(name) {
+    return this.call("DELETE", `/env/${encodeURIComponent(name)}`, EnvChangeSchema);
+  }
   // ---- volumes (#52) ----
   listVolumes(opts = {}) {
     return this.call("GET", `/volumes${allQuery(opts)}`, z3.array(VolumeSchema), void 0, opts.org);
@@ -2419,7 +2452,13 @@ var cancelled = () => new KvboxError("cancelled", 130);
 function keysIn(chunk) {
   const keys = [];
   for (let i = 0; i < chunk.length; ) {
-    if (chunk[i] === ESC && (chunk[i + 1] === "[" || chunk[i + 1] === "O") && i + 2 < chunk.length) {
+    if (chunk[i] === ESC && chunk[i + 1] === "[" && i + 2 < chunk.length) {
+      let j = i + 2;
+      while (j < chunk.length && /[0-9;?]/.test(chunk[j])) j += 1;
+      const end = j < chunk.length ? j + 1 : j;
+      keys.push(chunk.slice(i, end));
+      i = end;
+    } else if (chunk[i] === ESC && chunk[i + 1] === "O" && i + 2 < chunk.length) {
       keys.push(chunk.slice(i, i + 3));
       i += 3;
     } else {
@@ -2496,7 +2535,8 @@ async function text(message, opts = {}) {
     const hint = opts.default !== void 0 ? ` ${color.dim(`(${opts.default})`)}` : "";
     const question = `${color.green("?")} ${color.bold(message)}${hint} ${color.dim("\u203A")} `;
     const rl = createInterface({ input: process.stdin, output: out });
-    const raw = (await askLine(rl, question)).trim();
+    const line = await askLine(rl, question);
+    const raw = opts.trim === false ? line : line.trim();
     const answer = raw === "" && opts.default !== void 0 ? opts.default : raw;
     const problem = opts.validate?.(answer);
     out.write(`${ESC}[${rows(question + raw)}A\r${ESC}[J`);
@@ -2509,6 +2549,44 @@ async function text(message, opts = {}) {
 `);
   }
 }
+async function hiddenText(message) {
+  const out = process.stderr;
+  const inp = process.stdin;
+  const question = `${color.green("?")} ${color.bold(message)} ${color.dim("(hidden) \u203A")} `;
+  out.write(question);
+  inp.setRawMode(true);
+  inp.resume();
+  inp.setEncoding("utf8");
+  let chars = [];
+  let done = false;
+  try {
+    return await new Promise((resolve3, reject) => {
+      const onData = (chunk) => {
+        for (const key of keysIn(chunk)) {
+          if (key === ENTER || key === "\n") {
+            inp.off("data", onData);
+            done = true;
+            resolve3(chars.join(""));
+            return;
+          }
+          if (key === CTRL_C || key === CTRL_D) {
+            inp.off("data", onData);
+            reject(cancelled());
+            return;
+          }
+          if (key === "\x7F" || key === "\b") chars = chars.slice(0, -1);
+          else if (key.length === 1 && (key >= " " || key === "	")) chars.push(key);
+        }
+      };
+      inp.on("data", onData);
+    });
+  } finally {
+    inp.setRawMode(false);
+    inp.pause();
+    out.write(`\r${ESC}[J${done ? `${settled(message, "\u2022\u2022\u2022\u2022\u2022")}
+` : "\n"}`);
+  }
+}
 async function askLine(rl, question) {
   let onClose = () => {
   };
@@ -3145,7 +3223,8 @@ var nextjsTemplate = {
    * The source lands in a staging directory and is installed and built there while the old app
    * keeps serving; only then is it swapped into place and the service restarted, so a failed
    * install or build leaves the running app alone. The unit is rewritten every time, so a changed
-   * package manager or start script takes effect. /srv/app is the kvbox user's (image v0.8.0+).
+   * package manager or start script takes effect. /srv/app is the kvbox user's (image v0.8.0+). The
+   * build runs in the deploy's SSH session, so it sees the owner's variables (`kvbox env`) too.
    */
   remote(built) {
     const c = commands(built.pm);
@@ -3157,8 +3236,12 @@ var nextjsTemplate = {
       "[Service]",
       "User=kvbox",
       `WorkingDirectory=${APP_DIR}`,
-      `ExecStart=/usr/bin/env ${c.start}`,
-      `Environment=NODE_ENV=production PORT=${PORT}`,
+      // PORT on the command line: the proxied address points at it, and nothing in the environment
+      // file below may move the app off it (env's PORT, say, copied from a .env).
+      `ExecStart=/usr/bin/env PORT=${PORT} ${c.start}`,
+      "Environment=NODE_ENV=production",
+      // The box owner's variables (#88, base v0.10.0+; the `-` makes an older box start without them).
+      "EnvironmentFile=-/etc/kvbox/env",
       "Restart=always",
       "RestartSec=2",
       "",
@@ -3556,6 +3639,10 @@ import { Command as Command56 } from "commander";
 
 // src/commands/volume/attach.ts
 import { Command as Command51 } from "commander";
+function describeMount(machine, volume, box) {
+  const path = machine.volumes?.find((v) => volume === v.name || volume.endsWith(`/${v.name}`))?.mountPath ?? volumeMountPath(volume.slice(volume.lastIndexOf("/") + 1));
+  return machine.status === "running" ? `  the box was restarted; the volume is at ${path} inside it` : `  box ${box} is ${machine.status}; the volume is at ${path} once it runs`;
+}
 var attachCommand = new Command51("attach").description("attach a volume to a box at /mnt/<volume> (a running box is restarted to take it)").argument("<volume>", "volume name").argument("<box>", "box name").option("--json", "print the box as JSON").action(async (volume, box, opts, cmd) => {
   const client = await clientFor(cmd.optsWithGlobals());
   try {
@@ -3564,9 +3651,8 @@ var attachCommand = new Command51("attach").description("attach a volume to a bo
       json(machine);
       return;
     }
-    const path = machine.volumes?.find((v) => volume === v.name || volume.endsWith(`/${v.name}`))?.mountPath ?? volumeMountPath(volume.slice(volume.lastIndexOf("/") + 1));
     info(`${color.green("\u2713")} volume ${volume} attached to box ${box}`);
-    info(machine.status === "running" ? `  the box was restarted; the volume is at ${path} inside it` : `  box ${box} is ${machine.status}; the volume is at ${path} once it runs`);
+    info(describeMount(machine, volume, box));
   } finally {
     await client.close();
   }
@@ -3581,13 +3667,25 @@ function parseGib2(text2) {
   if (gib > MAX_VOLUME_GIB) throw new KvboxError(`--size ${text2}: a volume is at most ${MAX_VOLUME_GIB} GB`);
   return gib;
 }
-var createCommand = new Command52("create").alias("new").description("create a volume: an empty disk of its own, ready to attach to a box").argument("<name>", "volume name (1-12 chars; the box mounts it at /mnt/<name>)").requiredOption("--size <gb>", "size in GB, like 50 or 50GB (whole GB; it only occupies what is written)").option("--box <box>", "the box it is for: made on that box's host (a volume attaches only to a box on its own host)").option("--json", "print the volume as JSON").action(async (name, opts, cmd) => {
+var createCommand = new Command52("create").alias("new").description("create a volume for a box: an empty disk of its own at /mnt/<name> inside it (a running box is restarted)").argument("<name>", "volume name (1-12 chars; the box mounts it at /mnt/<name>)").requiredOption("--size <gb>", "size in GB, like 50 or 50GB (whole GB; it only occupies what is written)").option("--box <box>", "the box it is for: made on that box's host and attached to it (required on kvbox.sh; optional with --local)").option("--json", "print the volume as JSON").action(async (name, opts, cmd) => {
   const sizeGib = parseGib2(opts.size);
   const client = await clientFor(cmd.optsWithGlobals());
   try {
+    if (opts.box === void 0 && client.target.kind === "cloud") {
+      throw new KvboxError(`a volume is made for a box, on that box's host: kvbox volume create ${name} --size ${sizeGib} --box <box>`);
+    }
     const vol = await spin(`creating volume ${name} (${sizeGib} GB)\u2026`, client.createVolume({ name, sizeGib, ...opts.box !== void 0 ? { box: opts.box } : {} }));
-    if (opts.json) json(vol);
-    else info(`${color.green("\u2713")} volume ${name} created (${vol.sizeGib} GB); attach it to a box with: kvbox volume attach ${name} ${opts.box ?? "<box>"}`);
+    if (opts.box === void 0) {
+      if (opts.json) json(vol);
+      else info(`${color.green("\u2713")} volume ${name} created (${vol.sizeGib} GB); attach it to a box with: kvbox volume attach ${name} <box>`);
+      return;
+    }
+    const machine = await spin(`attaching volume ${name} to box ${opts.box} (a running box is restarted)\u2026`, client.attachVolume(name, { box: opts.box }));
+    if (opts.json) json({ ...vol, attachedTo: machine.name });
+    else {
+      info(`${color.green("\u2713")} volume ${name} created (${vol.sizeGib} GB) and attached to box ${opts.box}`);
+      info(describeMount(machine, name, opts.box));
+    }
   } finally {
     await client.close();
   }
@@ -3662,12 +3760,128 @@ var rmCommand6 = new Command55("rm").alias("remove").description("delete a volum
 var volumeCommand = new Command56("volume").aliases(["volumes", "vol"]).description("disks of their own: create one, attach it to a box at /mnt/<name>, move it to another box later").addCommand(createCommand).addCommand(lsCommand6).addCommand(attachCommand).addCommand(detachCommand).addCommand(rmCommand6);
 for (const cmd of volumeCommand.commands) cmd.option("--org <slug>", "act in this org (- for your personal volumes)");
 
+// src/commands/env/index.ts
+import { Command as Command60 } from "commander";
+
+// src/commands/env/ls.ts
+import { Command as Command57 } from "commander";
+
+// src/commands/env/shared.ts
+function requireCloud2(client) {
+  if (client.target.kind === "local") throw new KvboxError("kvbox env needs kvbox.sh: kvbox login first");
+  return client.target.org ?? client.target.user ?? "you";
+}
+function reach(boxes, verb) {
+  if (boxes === 0) return verb === "get" ? "no boxes yet, every new one gets it" : "no boxes yet";
+  return boxes === 1 ? `1 box ${verb}s it when it next starts` : `${boxes} boxes ${verb} it when they next start`;
+}
+
+// src/commands/env/ls.ts
+var lsCommand7 = new Command57("ls").alias("list").description("list the variables (a secret shows as (sealed))").option("--json", "print as JSON").action(async (opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    const vars = await client.listEnv();
+    if (opts.json) {
+      json(vars);
+      return;
+    }
+    if (vars.length === 0) {
+      info(`no variables for ${owner} yet; set one with: kvbox env set NAME value`);
+      return;
+    }
+    table(vars.map((v) => ({ name: v.name, value: v.secret ? color.dim("(sealed)") : v.value, updated: age(v.updatedAt) })));
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/rm.ts
+import { Command as Command58 } from "commander";
+var rmCommand7 = new Command58("rm").alias("remove").description("remove variables; boxes lose them when they next start").argument("<names...>", "variable names").option("-y, --yes", "do not ask for confirmation").option("--json", "print as JSON").action(async (names, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    if (!await confirm(`Remove ${names.join(", ")} from ${owner}'s variables?`, opts.yes ?? false)) {
+      info("cancelled");
+      process.exitCode = 1;
+      return;
+    }
+    const changes = [];
+    const failed = [];
+    for (const name of names) {
+      try {
+        const c = await spin(`removing ${name}\u2026`, client.removeEnv(name));
+        changes.push(c);
+        if (!opts.json) info(`${color.green("\u2713")} removed ${c.name} from ${owner}: ${reach(c.boxes, "lose")}`);
+      } catch (err) {
+        failed.push({ name, err });
+      }
+    }
+    if (changes.length === 0 && failed.length > 0) throw failed[0].err;
+    if (opts.json) json(changes);
+    for (const f of failed) warn(`${color.red("\u2717")} ${f.name}: ${f.err.message}`);
+    if (failed.length > 0) process.exitCode = 1;
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/set.ts
+import { Command as Command59 } from "commander";
+
+// ../shared/src/env.ts
+var ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ENV_RESERVED = ["PATH", "HOME", "USER", "SHELL"];
+var ENV_MAX_VALUE_BYTES = 4096;
+function envNameProblem(name) {
+  if (!ENV_NAME_RE.test(name)) return `${JSON.stringify(name)} is not a variable name: letters, digits and _, not starting with a digit`;
+  if (ENV_RESERVED.includes(name)) return `${name} is the box's own and cannot be set`;
+  if (name.startsWith("KVBOX_")) return `${name}: names starting with KVBOX_ are kept for kvbox`;
+  return null;
+}
+function envValueProblem(value) {
+  if (/[\n\r\0]/.test(value)) return "a value is one line: no line breaks (base64 a multi-line value such as a key file)";
+  if (Buffer.byteLength(value, "utf8") > ENV_MAX_VALUE_BYTES) return `a value is at most ${ENV_MAX_VALUE_BYTES / 1024} KB`;
+  return null;
+}
+
+// src/commands/env/set.ts
+var setCommand2 = new Command59("set").description("add or change a variable; boxes get it when they next start").argument("[name]", "variable name, e.g. DATABASE_URL (asked for when left out)").argument("[value]", "its value (asked for when left out; hidden with --secret)").option("--secret", "write-only: the value is never shown again, by any command").option("--json", "print as JSON").action(async (nameArg, valueArg, opts, cmd) => {
+  const client = await clientFor(cmd.optsWithGlobals(), { autoStart: false });
+  try {
+    const owner = requireCloud2(client);
+    const ask = interactive();
+    if ((nameArg === void 0 || valueArg === void 0) && !ask) throw new KvboxError("give the name and the value: kvbox env set NAME VALUE (or run it in a terminal to be asked)");
+    const name = nameArg ?? await text("Variable name", { validate: (a) => envNameProblem(a) ?? void 0 });
+    const nameProblem = envNameProblem(name);
+    if (nameProblem !== null) throw new KvboxError(nameProblem);
+    const value = valueArg ?? (opts.secret ? await hiddenText(`Value for ${name}`) : await text(`Value for ${name}`, { trim: false }));
+    const valueProblem = envValueProblem(value);
+    if (valueProblem !== null) throw new KvboxError(valueProblem);
+    const change = await spin(`setting ${name}\u2026`, client.setEnv(name, { value, secret: opts.secret ?? false }));
+    if (opts.json) {
+      json(change);
+      return;
+    }
+    const what = opts.secret ? `${name} (secret)` : name;
+    info(`${color.green("\u2713")} set ${what} for ${owner}: ${reach(change.boxes, "get")}`);
+  } finally {
+    await client.close();
+  }
+});
+
+// src/commands/env/index.ts
+var envCommand = new Command60("env").description("environment variables every box of yours gets when it starts (secrets too)").addCommand(lsCommand7, { isDefault: true }).addCommand(setCommand2).addCommand(rmCommand7);
+for (const cmd of envCommand.commands) cmd.option("--org <slug>", "the org's variables instead of yours");
+
 // src/program.ts
 function buildProgram() {
-  const program = new Command57("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 Command61("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(volumeCommand);
+  program.addCommand(envCommand);
   program.addCommand(serverCommand);
   program.addCommand(loginCommand);
   program.addCommand(logoutCommand);