@tonbo/cli 0.17.3 → 0.19.0

package/README.md

@@ -26,7 +26,7 @@ The login file, `login.json`, and the device id it is tied to are shared with [`
 
 ## Commands and the Management API
 
-Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. The command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
+Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. `tonbo volume move` is the one command that sends another command's operation: it reads the Volume and both Machines and sends the target's `updateMachine` with `move_from` (the `machine create --move-from` of an existing Machine, docs/design/machines-volume-move.md). Apart from it, the command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
 
 The help lives with the commands: [`src/app.ts`](src/app.ts) defines each command, its arguments and flags with their one-line descriptions, and [`src/help.ts`](src/help.ts) holds the long help, each flag's default, the examples, the shared rules and the environment. [`commands.json`](commands.json) is all of it as `--help` prints it, which the docs' CLI reference renders; `test/commands.test.ts` holds it to the program, and holds every runnable command to its details and example and the environment list to the variables the code reads, so after changing a command run `pnpm --filter @tonbo/cli commands`.
 

package/dist/bin/tonbo.js

@@ -402,6 +402,7 @@ var managementOperations = {
     "query": [
       "origin",
       "scope",
+      "owners",
       "cursor",
       "limit"
     ],
@@ -2362,7 +2363,8 @@ var ManagementApi = class {
         return {
           machine: answer.data,
           location: headers.location,
-          retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+          retryAfterSeconds: retryAfterSeconds(headers.retryAfter),
+          volumeMove: answer.volume_move ?? null
         };
       } catch (error) {
         if (error instanceof HttpError && error.status < 500)
@@ -2425,6 +2427,13 @@ var ManagementApi = class {
       ifMatch: etag
     });
   }
+  /** An update whose binding names `move_from`: the Machine, and what the
+   * move did, which the answer carries beside it
+   * (docs/design/machines-volume-move.md). */
+  async moveVolume(key, name, etag, change) {
+    const answer = await this.request("updateMachine", key, { params: { name }, body: withoutUndefined(change), ifMatch: etag });
+    return { machine: answer.data, volumeMove: answer.volume_move ?? null };
+  }
   /** With `etag`, only the Machine that ETag names, at that revision, is put
    * to sleep (machine-v2.json `etag.if_match.sleep` is optional). A 202
    * carries the `Retry-After` to read the Machine again after
@@ -5519,12 +5528,73 @@ async function volumeDeleteCommand(deps, name, options = {}) {
     );
   });
 }
-async function resolveVolumeBinding(deps, key, spec) {
+function movedText(move, volume, target) {
+  return [
+    `Moved Volume ${volume} from ${move.from} to ${target}; it attaches at ${target}'s next boot, and ${move.from} boots without it.`,
+    ...move.replaced ? [
+      `${target}'s Volume ${move.replaced.name} was unbound and kept; bind it again with \`tonbo machine update <machine> --volume ${move.replaced.name}:<path>\`.`
+    ] : []
+  ];
+}
+async function volumeMoveCommand(deps, name, options = {}) {
+  await volumeCommand(deps, async () => {
+    if (!options.to) throw new Error("Pass --to <machine>.");
+    const to = options.to;
+    const key = await deps.auth.apiKey();
+    const volume = await deps.api.getVolume(key, name);
+    const from = volume.machine?.name ?? null;
+    if (from === to && options.path === void 0) {
+      print(
+        deps,
+        options.json,
+        volume,
+        `Volume ${volume.name} is already on ${to}; nothing to move.`
+      );
+      return;
+    }
+    const { machine: target, etag } = await deps.api.getMachineWithEtag(key, to);
+    if (target.kind === "byoc")
+      throw new Error(
+        `${to} is one of your computers; a Volume moves only to a Machine Tonbo runs.`
+      );
+    if (etag === null) throw new Error(`The API answered ${to} without an ETag.`);
+    const binding = { volume: volume.id };
+    let path6 = options.path;
+    if (from !== null && from !== to) {
+      const { machine: source, etag: sourceTag } = await deps.api.getMachineWithEtag(key, from);
+      const held = source.kind === "managed" ? source.volumes?.find((entry) => entry.volume === volume.id) : void 0;
+      path6 ??= held?.path;
+      binding.move_from = from;
+      if (sourceTag !== null) binding.move_from_etag = sourceTag;
+    }
+    if (path6 !== void 0) binding.path = path6;
+    const { machine, volumeMove: move } = await deps.api.moveVolume(key, to, etag, {
+      volumes: [binding]
+    });
+    print(
+      deps,
+      options.json,
+      machine,
+      move ? movedText(move, volume.name, machine.name).join("\n") : `Bound Volume ${volume.name} to ${machine.name}${path6 === void 0 ? " as its whole disk" : ` at ${path6}`}; it attaches at the next boot.`
+    );
+  });
+}
+function parseVolumeSpec(spec) {
   const split = spec.indexOf(":");
+  if (split === -1 && spec.length > 0) return { name: spec };
   if (split < 1 || split === spec.length - 1)
-    throw new Error(`--volume ${spec}: give <name>:<path>, such as data:/data.`);
-  const volume = await deps.api.getVolume(key, spec.slice(0, split));
-  return { binding: { volume: volume.id, path: spec.slice(split + 1) }, region: volume.region };
+    throw new Error(
+      `--volume ${spec}: give <name> for the Machine's whole disk, or <name>:<path> to mount it at a path, such as data:/data.`
+    );
+  return { name: spec.slice(0, split), path: spec.slice(split + 1) };
+}
+async function resolveVolumeBinding(deps, key, spec) {
+  const { name, path: path6 } = parseVolumeSpec(spec);
+  const volume = await deps.api.getVolume(key, name);
+  return {
+    binding: path6 === void 0 ? { volume: volume.id } : { volume: volume.id, path: path6 },
+    region: volume.region
+  };
 }
 
 // src/machine.ts
@@ -5550,6 +5620,13 @@ var MACHINE_ERROR_HINTS = {
   image_failed: "The Machine's image could not be pulled; `tonbo machine show` says why. Fix the image, then name it again with `tonbo machine update --image`.",
   machine_kind_mismatch: "That Machine is one of your computers: `tonbo machine show` and `tonbo machine delete` serve it, and nothing else does.",
   volumes_not_offered: "Volumes are not offered to this account in the Machine's region yet; nothing was created or changed.",
+  root_mode_not_offered: "A Volume as the Machine's whole disk is not offered to this account yet; nothing was created or changed. Mount it at a path instead: --volume <name>:<path>.",
+  rebuild_required: "This Machine's Volume is its whole disk, so its image changes only by Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk. Rebuild is not available yet: keep the image, or create a new Machine with the new image and a new Volume.",
+  volume_mode_change: "The Volume cannot move between being the Machine's whole disk and being mounted at a path; nothing was changed. Bind a new Volume in the mode you want.",
+  volume_attached: "The Machine the message names is awake with the Volume attached; nothing was changed. Put it to sleep with `tonbo machine sleep <machine>`, then run the command again.",
+  volume_holder_changed: "The Volume is not on the Machine you named; nothing was changed. `tonbo volume show <volume>` says which Machine has it: name that one, or use `tonbo volume move`.",
+  volume_image_mismatch: "The Volume is a Machine's whole disk, made against one image; it moves only to a Machine on that same image. Nothing was changed.",
+  volume_rebuild_pending: "The Volume's Rebuild has not finished; move it once it has. Nothing was changed.",
   secret_env_conflict: "Use another secret key or remove the non-secret env variable with that name.",
   secret_limit: "Reduce the number or byte size of this Machine's secrets.",
   wake_unavailable: "The wake was refused for now; nothing woke. Wake it again after a while; `tonbo machine show` says why it is blocked."
@@ -5812,7 +5889,8 @@ function deleteFields(machine) {
 }
 function volumeText(machine) {
   const binding = machine.volumes?.[0];
-  return binding ? `${binding.volume} at ${binding.path}` : "none";
+  if (!binding) return "none";
+  return binding.path === void 0 ? `${binding.volume} (whole disk)` : `${binding.volume} at ${binding.path}`;
 }
 function machineText(machine, billing, etag = null, lastEnd = null) {
   return [machineFields(machine, billing, etag, lastEnd), ...privatePortLines(machine)].join("\n");
@@ -6117,12 +6195,22 @@ async function waitForCreate(deps, key, machine, name, firstWait, timeout, json)
 async function machineCreateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (!options.image) throw new Error("Pass --image <reference>.");
+    if (options.moveFrom !== void 0 && typeof options.volume !== "string")
+      throw new Error("--move-from names the Machine that holds the --volume: pass --volume too.");
     const timeout = waitTimeout(options);
     const env = parseEnv(options.env ?? []);
     const secrets = createSecrets(options);
     const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
     const bound = typeof options.volume === "string" ? await resolveVolumeBinding(deps, key, options.volume) : null;
+    if (bound && options.moveFrom !== void 0) {
+      const { etag } = await deps.api.getMachineWithEtag(key, options.moveFrom);
+      bound.binding = {
+        ...bound.binding,
+        move_from: options.moveFrom,
+        ...etag === null ? {} : { move_from_etag: etag }
+      };
+    }
     const database = typeof options.database === "string" ? await deps.api.getDatabase(key, options.database) : null;
     if (database && bound && database.region !== bound.region && !options.region)
       throw new Error(
@@ -6182,7 +6270,11 @@ async function machineCreateCommand(deps, name, command, options = {}) {
       deps,
       options.json,
       machine,
-      [createdText(machine), machineText(machine, await billingUrl(deps))].join("\n")
+      [
+        createdText(machine),
+        ...created.volumeMove ? movedText(created.volumeMove, options.volume, machine.name) : [],
+        machineText(machine, await billingUrl(deps))
+      ].join("\n")
     );
   });
 }
@@ -6886,11 +6978,15 @@ var COMMAND_HELP = {
   },
   "tonbo machine create": {
     about: [
-      "Creates a Machine, a VM booted from an image in one region. It has no database of its own: `--database <name>` binds one of the account's databases of its region, which it then reaches at `TONBO_DATABASE_URL`, and a database binds one Machine at a time; its files can last on a Volume (`--volume`), and its program can open any other database by URL with a key. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
+      "Creates a Machine, a VM booted from an image in one region. It has no database of its own: `--database <name>` binds one of the account's databases of its region, which it then reaches at `TONBO_DATABASE_URL`, and a database binds one Machine at a time; its disk can last on a Volume (`--volume <name>` keeps the Machine's whole disk on it, and `--volume <name>:<path>` mounts it at a path instead), and its program can open any other database by URL with a key. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
       "The Machine is served at `https://<name>-<account>.tonbo.sh` on its default port. `--port <port>` serves a private port, which takes a member's token, and `--port <port>:public` an open one, which needs the `machines.public` capability. A command after `--` replaces the image's CMD. `--secret-env KEY=FILE` and `--secret-file KEY=FILE` read initial secrets from local files and store them with the Machine before its first boot; their values are never returned. The CLI warns on stderr when the Machine has no port, since nothing can wake it then, and when an `--env` key looks secret: env values are readable by every member through the API.",
+      "`--move-from <machine>` takes the `--volume` from the Machine that has it now, in the same write as the create: that Machine's binding is removed (its ETag changes) and it boots without the Volume. It is refused while that Machine is awake with the Volume attached (`volume_attached`: `tonbo machine sleep <machine>` first), or when another Machine has the Volume (`volume_holder_changed`); either way nothing is created or changed. Without it, a Volume another Machine has is refused.",
       "The answer is the Machine while it is `creating`. With `--wait` the CLI reads it until it is `active` or `failed`, or `--timeout` passes: a failure prints what to do and exits 1, and a timeout says it is still creating and undoes nothing. A creation the network or a 5xx answer did not confirm is sent at most three times with the same idempotency key, each retry after its `Retry-After` (at most 30 s) or a short backoff; a `name_taken` refusal says which Machine holds the name and how old it is, in case it is yours from a lost reply. In a region not open for Machines the creation is refused with `region_not_offered`, and nothing is created."
     ],
-    examples: ["tonbo machine create web --image nginx:1.27 --port 80:public --wait"],
+    examples: [
+      "tonbo machine create web --image nginx:1.27 --port 80:public --wait",
+      "tonbo machine create agent --image nginx:1.27 --volume data:/workspace --move-from worker"
+    ],
     arguments: {
       name: "the Machine's name, part of its hostname",
       command: "the command that replaces the image's CMD, after `--`"
@@ -6937,7 +7033,7 @@ var COMMAND_HELP = {
   "tonbo machine update": {
     about: [
       "Changes only what its options name. It reads the Machine and sends the ETag it read, or `--if-match`'s, so a change someone made in between is refused with `precondition_failed` rather than overwritten; a Machine whose creation failed is refused with `machine_failed`. `--env` and `--unset-env` change single variables; `--port` replaces every port, and the current default port stays the default while it is still listed.",
-      "Ports and `--sleep-after` apply at once. The image, command, shape, env, Volume and database apply at the next boot, and the command says how to apply them now: `tonbo machine sleep`, after which the next request boots the new spec. Naming the same tag again resolves its digest again. `--database <name>` binds another database of the account in the Machine's region, which no other Machine binds, and `--no-database` binds none; the database it leaves is kept. A Machine created with its own database keeps it.",
+      "Ports and `--sleep-after` apply at once. The image, command, shape, env, Volume and database apply at the next boot, and the command says how to apply them now: `tonbo machine sleep`, after which the next request boots the new spec. Naming the same tag again resolves its digest again. A Machine whose Volume is its whole disk keeps its image: another image is refused with `rebuild_required`, since only Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk, may move it, and Rebuild is not available yet. `--database <name>` binds another database of the account in the Machine's region, which no other Machine binds, and `--no-database` binds none; the database it leaves is kept. A Machine created with its own database keeps it.",
       "`--delete-after` applies at once and keeps the clock, which counts from the end of the Machine's last activation (or its creation), so a lower value can delete a Machine that has already slept that long; `--no-delete-after` turns it off. `tonbo machine show` prints when it will be deleted."
     ],
     examples: ["tonbo machine update web --env MODE=staging --sleep-after 300"],
@@ -7155,6 +7251,15 @@ var COMMAND_HELP = {
     examples: ["tonbo volume show data"],
     arguments: NAME("Volume")
   },
+  "tonbo volume move": {
+    about: [
+      "Moves the Volume to the Machine `--to`, taking it from the Machine that has it now in one write: the Volume is unbound there (that Machine's ETag changes and it boots without it) and bound to `--to`, which may be awake and gets it at its next boot. The CLI reads both Machines' ETags first, so a Machine changed since is refused, never overwritten. Without `--path` the Volume keeps the path it has now, or stays a whole disk; a whole disk moves only to a Machine on the same image.",
+      'The Machine that has it must be asleep: an awake one is refused with `volume_attached`, and nothing changes; `tonbo machine sleep <machine>` first. When `--to` already has another Volume, that one is unbound and kept, and the CLI names it. The REST equivalent is `PATCH /v1/machines/<to>` with `If-Match: <its ETag>` and `{"volumes": [{"volume": "<id>", "path": "<path>", "move_from": "<machine>", "move_from_etag": "<its ETag>"}]}`.'
+    ],
+    examples: ["tonbo volume move data --to agent --path /workspace"],
+    arguments: NAME("Volume"),
+    defaults: { "--path": "the path the Volume has now, or none (a whole disk)" }
+  },
   "tonbo volume delete": {
     about: [
       "Deletes the Volume and every byte on it; there are no Volume snapshots or backups. It is refused while a Machine has it. At a terminal it asks you to type the Volume's name first."
@@ -8556,8 +8661,8 @@ function machineSpecOptions(command, update) {
     "the seconds between SIGTERM and SIGKILL on a planned stop",
     parseWhole
   ).option(
-    "--volume <name:path>",
-    `mount the Volume <name> (see tonbo volume list) at <path>; a Machine has at most one, of its own region${update ? "; applies at the next boot" : ""}`
+    "--volume <name[:path]>",
+    `keep the Machine's whole disk on the Volume <name> (see tonbo volume list), or with :<path> mount it at <path> instead; a Machine has at most one, of its own region${update ? "; applies at the next boot" : ""}`
   ).option(
     "--delete-after <seconds>",
     `delete the Machine once it has been asleep, never woken or failed this long (3600 to 7776000)${update ? "; applies at once, from its last activation's end" : ""}`,
@@ -8902,6 +9007,9 @@ function createProgram(makeDependencies = createDependencies) {
       "read a UTF-8 environment secret from FILE; repeat",
       repeated
     ).option("--secret-file <KEY=FILE>", "read binary file secret from FILE; repeat", repeated).option(
+      "--move-from <machine>",
+      "take the --volume from the asleep Machine <machine> that has it, in the same write; that Machine boots without it"
+    ).option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the Machine it created"
     ).option("--wait", "wait until the Machine is active, or say why it failed").option("--timeout <seconds>", "how long --wait waits, in seconds", parseWhole),
@@ -9103,6 +9211,17 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, options) => volumeShowCommand(dependencies(), name, options)
   );
+  operationOptions(
+    volume.command("move <name>").description(
+      "move a Volume to another Machine of its region, taking it from the asleep Machine that has it in the same write"
+    ).requiredOption("--to <machine>", "the Machine that gets the Volume; it may be awake").option(
+      "--path <path>",
+      "mount it at <path> there; without it, it keeps the path it has now, or stays a whole disk"
+    ),
+    "updateMachine"
+  ).action(
+    async (name, options) => volumeMoveCommand(dependencies(), name, options)
+  );
   operationOptions(
     volume.command("delete <name>").description("delete a Volume and its data; refused while a Machine has it").option("--yes", "delete without asking; required when stdin is not a terminal"),
     "deleteVolume"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.17.3",
+  "version": "0.19.0",
   "description": "The Tonbo CLI. Compute, disks, databases and streams for AI agents: your agent picks what it needs, sets it up, and knows what it costs, from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {