@tonbo/cli 0.8.0 → 0.9.0

package/README.md

@@ -27,7 +27,7 @@ The login and the credentials file are shared with [`yield`](../yield) through `
 
 ## Commands and the Management API
 
-Every command other than `login` and `logout` calls one operation of the [Management API](../../contracts/management/openapi-v1.yaml) and is named by that operation's `x-tonbo-cli`; 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` and `logout` are the named exception: they obtain and discard the key the other commands present as their Bearer credential. What a command may do is what your role in the logged-in account 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`, or the Machine a `name_taken` refusal names); `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` and `logout` are the named exception: they obtain and discard the key the other commands present as their Bearer credential. What a command may do is what your role in the logged-in account allows; the CLI never decides it.
 
 | Command | Operation | Request |
 | --- | --- | --- |
@@ -60,11 +60,11 @@ Every command other than `login` and `logout` calls one operation of the [Manage
 | `tonbo stream usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--names <a,b>] [--limit <n>] [--cursor <c>]` | `listStreamUsage` | `GET /v1/usage/streams` |
 | `tonbo usage show [--period <YYYY-MM>]` | `getUsage` | `GET /v1/usage` |
 | `tonbo machine list [--limit <n>] [--cursor <c>]` | `listMachines` | `GET /v1/machines` |
-| `tonbo machine create <name> --image <reference> [--shape <shape>] [--region <region>] [--port <port[:access]>]… [--default-port <port>] [--env <KEY=VALUE>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--idempotency-key <key>] [-- <command>…]` | `createMachine` | `POST /v1/machines` |
+| `tonbo machine create <name> --image <reference> [--shape <shape>] [--region <region>] [--port <port[:access]>]… [--default-port <port>] [--env <KEY=VALUE>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--idempotency-key <key>] [--wait [--timeout <seconds>]] [-- <command>…]` | `createMachine` | `POST /v1/machines` |
 | `tonbo machine show <name>` | `getMachine` | `GET /v1/machines/{name}` |
-| `tonbo machine update <name> [--image <reference>] [--image-command] [--shape <shape>] [--port <port[:access]>]… [--clear-ports] [--default-port <port>] [--env <KEY=VALUE>]… [--unset-env <KEY>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--discard-snapshot] [--revision <n>] [-- <command>…]` | `updateMachine` | `PATCH /v1/machines/{name}` |
-| `tonbo machine sleep <name>` | `sleepMachine` | `POST /v1/machines/{name}/sleep` |
-| `tonbo machine delete <name> [--yes]` | `deleteMachine` | `DELETE /v1/machines/{name}` |
+| `tonbo machine update <name> [--image <reference>] [--image-command] [--shape <shape>] [--port <port[:access]>]… [--clear-ports] [--default-port <port>] [--env <KEY=VALUE>]… [--unset-env <KEY>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--discard-snapshot] [--if-match <etag>] [-- <command>…]` | `updateMachine` | `PATCH /v1/machines/{name}` |
+| `tonbo machine sleep <name> [--if-match <etag>] [--wait [--timeout <seconds>]]` | `sleepMachine` | `POST /v1/machines/{name}/sleep` |
+| `tonbo machine delete <name> [--yes] [--if-match <etag>]` | `deleteMachine` | `DELETE /v1/machines/{name}` |
 | `tonbo machine shapes` | `listMachineShapes` | `GET /v1/machine-shapes` |
 
 ### Output and errors
@@ -169,17 +169,21 @@ tonbo machine sleep web
 tonbo machine delete web
 ```
 
-A Machine is a VM booted from an image, in one region, with its own database (`contracts/machines/machine-v2.json`). Machines open by invitation: until a region is open for them, every `tonbo machine` command is refused with `region_unavailable`, and the CLI says that nothing was created or changed.
+A Machine is a VM booted from an image, in one region, with its own database (`contracts/machines/machine-v2.json`). Machines open by invitation: until a region is open for them, `machine create`, `update`, `sleep` and `delete` are refused with `region_not_offered`, and the CLI says that nothing was created or changed; `machine list`, `show` and `shapes` still answer. A region that cannot be reached is refused with `region_unavailable`, which a retry may clear.
 
 The image is `tonbo.dev/platform`, the platform image each node release ships, or, once registry images are offered, a public OCI image with a linux/arm64 variant. Until then any other reference is refused with `image_not_offered`, before anything is created or changed; `machine show` prints the platform image as `tonbo.dev/platform (platform image)`.
 
-`machine create` resolves a registry image to its linux/arm64 digest (the platform image resolves to none) and reserves the Machine's name and its hostnames: `https://<name>-<account>.<region>.tonbo.sh` for the default port, and `<name>.<account>@<region>.tonbo.sh` for SSH. Without `--shape` it takes the shape `machine shapes` marks as the default. `--port <port>` serves a private port (a member's token or SSH) and `--port <port>:public` an open one, which needs the `machines.public` capability; the first port is served at the hostname unless `--default-port` names another. A command after `--` replaces the image's CMD. The answer is the Machine while it is `creating`; `machine show` reports it `active` when it is ready.
+`machine create` resolves a registry image to its linux/arm64 digest (the platform image resolves to none) and reserves the Machine's name and its hostnames: `https://<name>-<account>.<region>.tonbo.sh` for the default port, and `<name>.<account>@<region>.tonbo.sh` for SSH, which `machine show` marks as not served yet. Without `--shape` it takes the shape `machine shapes` marks as the default. `--port <port>` serves a private port (a member's token) and `--port <port>:public` an open one, which needs the `machines.public` capability and has no wake-rate, concurrency or runtime limit; the first port is served at the hostname unless `--default-port` names another. A command after `--` replaces the image's CMD. The answer is the Machine while it is `creating`. With `--wait` the CLI reads the Machine at its `Location` after the answer's `Retry-After`, and again every `creation.poll_after_seconds`, until it is `active` or `failed` or `--timeout` (300 s by default) passes; a failure prints the Machine's failure with what to do and exits non-zero, and a timeout says it is still creating and undoes nothing. A create the network or a 5xx answer did not confirm is retried in the command with the same idempotency key, at most three times, honouring `Retry-After`; a `name_taken` refusal says which Machine holds the name and how old it is, in case it is yours from a lost reply.
 
-`machine update` changes only what its options name. It reads the Machine and writes the change at the revision it read, or at `--revision`, so a change someone made in between is refused with `revision_mismatch` rather than overwritten. `--env` and `--unset-env` change single variables; `--port` replaces every port, naming a public port again keeps its limits, and the current default port stays the default while it is still listed unless `--default-port` names another. Ports and `--sleep-after` apply at once; image, command, shape and env at the Machine's next boot. `machine sleep` puts an awake Machine to sleep now; its next connection wakes it. `machine delete` deletes the Machine with its disk, database and logs, and its name is free for a new Machine at once.
+`machine create` and `machine update` warn on stderr when the Machine ends up with no port (nothing can wake it until exec and SSH arrive) and when an `--env` key looks secret (`*_KEY`, `*_TOKEN`, `*SECRET*`, `*PASSWORD*`): env values are readable by every member through the API, and Machine secrets come later. When the default port is private, `machine create` and `machine show` print the `curl` call that reaches it with a personal key, and say that on a private port Tonbo authenticates the caller, so the app sees neither `Authorization` nor who called; an app with its own users serves a public port and does its own auth.
+
+`machine show` prints the state and what it means (an `active` Machine that is asleep boots on its first request, which the edge holds while it boots), the live activation and conditions when there are any, when the Machine sleeps and that its disk resets at every sleep until suspend ships, the database and logs URLs, a link to the durability text (the CLI prints the link only, never the text or a paraphrase of it), and the ETag. `machine show` prints image states as the API answers them: `pulling`, `ready`, `failed` or `not_pulled`.
+
+`machine update` 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, or another Machine that took the name, 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 unless `--default-port` names another. Ports and `--sleep-after` apply at once; image, command, shape and env apply at the next activation, and the command says how to apply them now: `machine sleep`, after which the next request boots the new spec; naming the same tag again re-resolves its digest. `machine sleep` puts an awake Machine to sleep now, and says so when it is already asleep or still creating; with `--wait` it reads the Machine until it is asleep. `machine delete` sends the ETag it read when it asked for confirmation, and `machine sleep` and `machine delete` send `--if-match`'s when given. `--if-match` takes the ETag `machine show` prints, with or without its double quotes: a value with neither a leading `"` nor `W/"` is quoted again, since a shell drops the quotes of a pasted tag. `machine shapes` prints each shape's list price for an hour at full use. `machine delete` deletes the Machine with its disk, database and logs, and its name is free for a new Machine at once.
 
 In a personal account, `machine list`, `machine show` and `machine delete` also cover your own computers, which `yield login` registers (Machines of kind `byoc`, which run nothing Tonbo operates). They are served even while Machines are not open in any region. `machine list` prints them in a second table with their system, agent harnesses, when they last reported and the state of their login key; `machine show` adds the hostname and device id, which only you see. `machine delete` forgets a computer: it disappears from the list at once and its name is free once the forget completes. Forgetting does not revoke the computer's key, so a computer whose key is still active registers again at its next start; the command says so and suggests `yield logout` on it or `tonbo api-key revoke` first. An organization lists managed Machines only.
 
-A refusal of machine-v2's `errors` prints the server's detail and then what to do next, for example `machine shapes` for `shape_unavailable` or a shorter name for `hostname_too_long`.
+A refusal of machine-v2's `errors`, or of a shared code such as `region_not_offered`, `precondition_required` or `precondition_failed`, prints the server's detail and then what to do next, for example `machine shapes` for `shape_not_offered` or a shorter name for `hostname_too_long`.
 
 ## Usage
 

package/dist/bin/tonbo.js

@@ -858,6 +858,11 @@ var machinePortAccess = [
   "private",
   "public"
 ];
+var machineTimings = {
+  "pollAfterSeconds": 2,
+  "wakeHoldSeconds": 25,
+  "earlyReclaimSeconds": 120
+};
 
 // ../../packages/tonbo-cli-core/dist/src/credentials.js
 var DIRECTORY_MODE = Number.parseInt(credentialsContract.permissions.directory_mode, 8);
@@ -1185,10 +1190,12 @@ var ManagementApi = class {
   fetcher;
   apiOrigin;
   loginHint;
-  constructor(fetcher, apiOrigin2 = DEFAULT_API_ORIGIN, loginHint = DEFAULT_LOGIN_HINT) {
+  pause;
+  constructor(fetcher, apiOrigin2 = DEFAULT_API_ORIGIN, loginHint = DEFAULT_LOGIN_HINT, pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))) {
     this.fetcher = fetcher;
     this.apiOrigin = apiOrigin2;
     this.loginHint = loginHint;
+    this.pause = pause;
   }
   /** The answer's `data`. A refusal throws an HttpError naming the request id. */
   async call(operationId, key, request = {}) {
@@ -1356,36 +1363,111 @@ var ManagementApi = class {
   listMachines(key, page) {
     return this.page("listMachines", key, page);
   }
-  /** A replay with the same idempotency key returns the Machine the first
-   * request created. */
-  createMachine(key, request, idempotencyKey) {
-    return this.call("createMachine", key, {
-      body: withoutUndefined(request),
-      idempotencyKey
-    }).catch(unconfirmed("Machine creation", idempotencyKey, "the same arguments"));
+  /**
+   * A replay with the same idempotency key returns the Machine the first
+   * request created, so a transport failure or a 5xx answer is retried here
+   * with the same key, at most `CREATE_ATTEMPTS` times, after the answer's
+   * Retry-After (bounded) or a short backoff. A refusal is final; a create
+   * still unconfirmed after the last attempt names the key to retry with.
+   * The answer carries the Machine's `Location` and, while it is creating,
+   * the `Retry-After` to read it again after (machine-v2.json
+   * `creation.create_status`).
+   */
+  async createMachine(key, request, idempotencyKey) {
+    let last;
+    for (let attempt = 1; attempt <= CREATE_ATTEMPTS; attempt++) {
+      const headers = {
+        location: null,
+        retryAfter: null
+      };
+      try {
+        const answer = await this.request("createMachine", key, { body: withoutUndefined(request), idempotencyKey }, (response) => {
+          headers.location = response.headers.get("location");
+          headers.retryAfter = response.headers.get("retry-after");
+        });
+        return {
+          machine: answer.data,
+          location: headers.location,
+          retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+        };
+      } catch (error) {
+        if (error instanceof HttpError && error.status < 500)
+          throw error;
+        last = error;
+        if (attempt === CREATE_ATTEMPTS)
+          break;
+        const wait = retryAfterSeconds(headers.retryAfter) ?? attempt;
+        await this.pause(Math.min(wait, CREATE_RETRY_MAX_WAIT_SECONDS) * 1e3);
+      }
+    }
+    return unconfirmed("Machine creation", idempotencyKey, "the same arguments")(last);
+  }
+  /** The name of the Machine a create's `Location` names, when it is this
+   * client's origin and `getMachine`'s path; null otherwise, so the key is
+   * never sent to another origin and the caller reads the Machine by the
+   * name it created. */
+  machineNameAt(location) {
+    if (!location)
+      return null;
+    let url;
+    try {
+      url = new URL(location, this.apiOrigin);
+    } catch {
+      return null;
+    }
+    if (url.origin !== new URL(this.apiOrigin).origin || url.search || url.hash)
+      return null;
+    const prefix = `${managementApiBasePath}${managementOperations.getMachine.path.replace("{name}", "")}`;
+    if (!url.pathname.startsWith(prefix))
+      return null;
+    const segment = url.pathname.slice(prefix.length);
+    if (!segment || segment.includes("/"))
+      return null;
+    try {
+      return decodeURIComponent(segment);
+    } catch {
+      return null;
+    }
   }
   getMachine(key, name) {
     return this.call("getMachine", key, { params: { name } });
   }
-  /** Written only at `revision` (machine-v2 requires If-Match, the Machine's
-   * ETag); a stale one is refused with `revision_mismatch`. */
-  updateMachine(key, name, revision, change) {
+  /** The Machine with its ETag, which is opaque (machine-v2.json `etag`)
+   * and is sent back as it was read. */
+  async getMachineWithEtag(key, name) {
+    const headers = { etag: null };
+    const answer = await this.request("getMachine", key, { params: { name } }, (response) => {
+      headers.etag = response.headers.get("etag");
+    });
+    return { machine: answer.data, etag: headers.etag };
+  }
+  /** Written only to the Machine and revision `etag` names, the ETag as read
+   * (machine-v2 requires If-Match on update); a stale one is refused with
+   * `precondition_failed`. */
+  updateMachine(key, name, etag, change) {
     return this.call("updateMachine", key, {
       params: { name },
       body: withoutUndefined(change),
-      ifMatch: `"${revision}"`
+      ifMatch: etag
     });
   }
-  sleepMachine(key, name) {
-    return this.call("sleepMachine", key, { params: { name } });
+  /** With `etag`, only the Machine that ETag names, at that revision, is put
+   * to sleep (machine-v2.json `etag.if_match.sleep` is optional). */
+  sleepMachine(key, name, etag) {
+    return this.call("sleepMachine", key, {
+      params: { name },
+      ...etag ? { ifMatch: etag } : {}
+    });
   }
   /** The Machine being deleted or the device forgotten, with its kind; the
    * Machine is null when the API answered 204, whose `X-Tonbo-Machine-Kind`
    * says whether a name was released (`managed`: its create never reached its
-   * region) or a device was forgotten (`byoc`: its region held no row). */
-  async deleteMachine(key, name) {
+   * region) or a device was forgotten (`byoc`: its region held no row). With
+   * `etag`, only the Machine that ETag names is deleted
+   * (machine-v2.json `etag.if_match.delete` is optional). */
+  async deleteMachine(key, name, etag) {
     const headers = { kind: null };
-    const answer = await this.request("deleteMachine", key, { params: { name } }, (response) => {
+    const answer = await this.request("deleteMachine", key, { params: { name }, ...etag ? { ifMatch: etag } : {} }, (response) => {
       headers.kind = response.headers.get("x-tonbo-machine-kind");
     });
     if (answer?.data)
@@ -1397,6 +1479,13 @@ var ManagementApi = class {
     return this.request("listMachineShapes", key, {});
   }
 };
+var CREATE_ATTEMPTS = 3;
+var CREATE_RETRY_MAX_WAIT_SECONDS = 30;
+function retryAfterSeconds(value) {
+  if (value === null || !/^[0-9]+$/.test(value.trim()))
+    return null;
+  return Number(value.trim());
+}
 function withoutUndefined(value) {
   return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
 }
@@ -2330,16 +2419,19 @@ async function usageShowCommand(deps, options = {}) {
 // src/machine.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 var MACHINE_ERROR_HINTS = {
-  region_unavailable: "Machines are not open there yet, or that region cannot be reached from here; nothing was created or changed.",
+  region_not_offered: "Machines are not offered in that region yet; nothing was created or changed. Name a region where they are offered.",
+  region_unavailable: "That region cannot be reached right now; nothing was created or changed. Try again shortly.",
   name_taken: "Choose another name; `tonbo machine list` shows the account's Machines.",
   hostname_taken: "The hostname <name>-<account> is held by another Machine or account; choose another name.",
   hostname_too_long: "<name>-<account> must fit one hostname label; choose a shorter name.",
   account_name_unclaimed: "Claim a Tonbo ID for the account on the console's Profile page, then run the command again.",
   image_platform_unsupported: "Machines run linux/arm64: publish the image for that platform (for example `docker buildx build --platform linux/arm64`).",
   image_not_offered: "Only the platform image runs until image pulls ship: create or update the Machine with `--image tonbo.dev/platform`.",
-  shape_unavailable: "`tonbo machine shapes` lists the shapes a Machine may name now.",
+  shape_not_offered: "`tonbo machine shapes` lists the shapes a Machine may name now.",
   port_reserved: "Serve the application on another port.",
-  revision_mismatch: "The Machine changed since it was read; `tonbo machine show` it and run the update again.",
+  precondition_required: "The API needs the Machine's ETag for this change; `tonbo machine show` prints it, and the command sends the ETag it reads unless --if-match names one.",
+  precondition_failed: "The Machine changed since it was read, or another Machine now has its name; `tonbo machine show` it and run the command again.",
+  machine_failed: "A Machine whose creation failed does not change: `tonbo machine show` says why; delete it with `tonbo machine delete` and create it again.",
   snapshot_would_be_discarded: "Pass --discard-snapshot to apply the change at the next boot, which then starts fresh.",
   database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`) first.",
   idempotency_conflict: "That idempotency key belongs to another request: leave out --idempotency-key to create a new Machine.",
@@ -2354,6 +2446,28 @@ var MACHINE_IMAGE_FAILURE_HINTS = {
   image_too_large: "Make the image smaller (fewer or smaller layers)",
   image_unsupported: "Rebuild the image without the entry the message names"
 };
+var MACHINE_CREATION_FAILURE_HINTS = {
+  database_creation_failed: "The Machine's database could not be created; the message names the stream and the code. If the code is payment_required, add credit to the account first; then delete the Machine and create it again.",
+  database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`), then delete this Machine and create it again.",
+  payment_required: "The account's credit is exhausted: add credit to the account, then delete the Machine and create it again.",
+  ...Object.fromEntries(
+    Object.entries(MACHINE_IMAGE_FAILURE_HINTS).map(([code, hint]) => [
+      code,
+      `${hint}, then delete the Machine and create it again naming the fixed image.`
+    ])
+  )
+};
+function creationFailureText(machine) {
+  const { failure } = machine;
+  if (!failure) return { reason: "", hint: "" };
+  const hint = MACHINE_CREATION_FAILURE_HINTS[failure.code];
+  return { reason: ` (${failure.code}: ${failure.message})`, hint: hint ? `
+${hint}` : "" };
+}
+function ifMatchHeader(value) {
+  if (value === void 0) return void 0;
+  return value.startsWith('"') || value.startsWith('W/"') ? value : `"${value}"`;
+}
 function explainMachineError(error) {
   if (!(error instanceof HttpError) || error.code === null) return error;
   const hint = MACHINE_ERROR_HINTS[error.code];
@@ -2374,20 +2488,75 @@ function portText(port) {
 function machinePortsText(machine) {
   return machine.ports.length ? machine.ports.map(portText).join(", ") : "none";
 }
-function idleActionText(machine) {
+var { earlyReclaimSeconds, pollAfterSeconds, wakeHoldSeconds } = machineTimings;
+function machineState(machine) {
+  if (machine.failure)
+    return `${machine.state}: ${machine.failure.code}: ${machine.failure.message}`;
+  if (machine.state === "creating")
+    return `creating: not ready for requests yet; read it again in ${pollAfterSeconds} s, or create with --wait`;
+  return machine.state;
+}
+function powerText(machine) {
+  const { power } = machine.status;
+  if (machine.state !== "active") return power;
+  if (power === "asleep")
+    return `asleep: the first request boots it, and the edge holds that request for up to ${wakeHoldSeconds} s`;
+  if (power === "awake") return "awake: serving requests";
+  return power;
+}
+function duration(seconds) {
+  return seconds % 60 === 0 && seconds >= 120 ? `${seconds / 60} min` : `${seconds} s`;
+}
+function sleepText(machine) {
   const { action, reason } = machine.status.sleep;
-  if (action === machine.idle_action) return action;
-  return `${action} (${machine.idle_action} requested; ${reason.replaceAll("_", " ")})`;
+  const when2 = `after about ${duration(earlyReclaimSeconds)} idle (early) or at most ${machine.sleep_after_seconds} s without a connection`;
+  if (action !== "release") return `${when2}; it then ${action}s`;
+  return `${when2}; the disk resets at every sleep${reason === "suspend_unavailable" ? " until suspend ships" : ""}`;
 }
-function machineState(machine) {
-  return machine.failure ? `${machine.state}: ${machine.failure.code}: ${machine.failure.message}` : machine.state;
+function activationFields(machine) {
+  const { activation } = machine;
+  if (!activation) return [];
+  return [
+    [
+      "Activation",
+      `${activation.state} since ${activation.started_at} (wake ${activation.wake_gen}, from ${activation.source})`
+    ]
+  ];
+}
+function conditionText(condition) {
+  switch (condition.type) {
+    case "wake_blocked":
+      return `wake blocked (${condition.reason.replaceAll("_", " ")}) since ${condition.since}`;
+    case "node_unreachable":
+      return `its host is unreachable since ${condition.since}`;
+    case "egress_blocked":
+      return `outbound access blocked for the ${condition.scope} since ${condition.since}${condition.until ? ` until ${condition.until}` : ""}`;
+    default:
+      return JSON.stringify(condition);
+  }
+}
+function conditionFields(machine) {
+  return (machine.status.conditions ?? []).map((condition) => [
+    "Condition",
+    conditionText(condition)
+  ]);
+}
+var DURABILITY_LINK = "https://tonbo.dev/docs/machines/guarantees#sleep";
+var PRIVATE_PORTS_LINK = "https://tonbo.dev/docs/machines/requests#private-ports";
+function privatePortLines(machine) {
+  const port = machine.ports.find((entry) => entry.default);
+  if (!port || port.access !== "private") return [];
+  return [
+    `Port ${port.port} is private: call it with a personal key from \`tonbo api-key create\` (see ${PRIVATE_PORTS_LINK}):`,
+    `  curl -H "Authorization: Bearer $TONBO_KEY" ${machine.hostnames.https}/`,
+    "On a private port Tonbo authenticates the caller, and the app sees neither Authorization nor who called; an app with its own users serves a public port and does its own auth."
+  ];
 }
 function imageText(machine) {
   const { reference, repository, digest, state } = machine.image;
   if (digest === null) return `${reference} (platform image)`;
   const pulled = repository === null ? digest : `${repository}@${digest}`;
-  const pulling = state === "resolved" && (machine.state === "creating" || machine.state === "active");
-  return `${reference} (${pulled}, ${pulling ? "pulling" : state})`;
+  return `${reference} (${pulled}, ${state})`;
 }
 function imageNextStep(machine, hint) {
   if (machine.state === "deleting") return null;
@@ -2405,30 +2574,39 @@ function imageFailureFields(machine) {
     ...next ? [["Next step", next]] : []
   ];
 }
-function machineFields(machine) {
+function machineFields(machine, etag = null) {
   return fields([
     ["Name", machine.name],
     ["ID", machine.id],
     ["Region", machine.region],
     ["State", machineState(machine)],
-    ["Power", machine.status.power],
+    ["Power", powerText(machine)],
+    ...activationFields(machine),
+    ...conditionFields(machine),
+    ["Sleeps", sleepText(machine)],
     ["Shape", machine.shape],
     ["Image", imageText(machine)],
     ...imageFailureFields(machine),
     ["Command", machine.command ? machine.command.join(" ") : "the image's own"],
     ["Ports", machinePortsText(machine)],
     ["HTTPS", machine.hostnames.https],
-    ["SSH", machine.hostnames.ssh],
+    // The resource keeps the SSH destination as a receipt; SSH is not served
+    // before tier P3.
+    ["SSH", `${machine.hostnames.ssh} (not served yet)`],
     ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
-    ["Sleep after", `${machine.sleep_after_seconds}s without a connection`],
-    ["Idle action", idleActionText(machine)],
-    ["Stop grace", `${machine.stop_grace_seconds}s`],
-    ["Database", machine.database.name],
+    ["Stop grace", `${machine.stop_grace_seconds} s`],
+    ["Database", `${machine.database.name} (${machine.database.url})`],
+    ["Logs", machine.logs.url],
+    ["Durability", DURABILITY_LINK],
     ["Revision", String(machine.revision)],
+    ...etag ? [["ETag", etag]] : [],
     ["Created", machine.created_at],
     ["Updated", machine.updated_at]
   ]);
 }
+function machineText(machine, etag = null) {
+  return [machineFields(machine, etag), ...privatePortLines(machine)].join("\n");
+}
 function keyStateText(machine) {
   const state = machine.byoc.key_state;
   if (state === "active") return state;
@@ -2452,10 +2630,10 @@ function deviceFields(machine) {
     ["Updated", machine.updated_at]
   ]);
 }
-function anyMachineFields(machine) {
-  return machine.kind === "byoc" ? deviceFields(machine) : machineFields(machine);
+function anyMachineText(machine, etag = null) {
+  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, etag);
 }
-function parsePorts(specs, current) {
+function parsePorts(specs) {
   const accesses = machinePortAccess;
   return specs.map((spec) => {
     const match = /^([0-9]{1,5})(?::([a-z]+))?$/.exec(spec);
@@ -2464,14 +2642,7 @@ function parsePorts(specs, current) {
       throw new Error(
         `--port ${spec}: give <port> or <port>:<access>, access ${accesses.join(" or ")}.`
       );
-    const port = Number(match[1]);
-    const before = current.find((entry) => entry.port === port && entry.access === access);
-    return {
-      port,
-      access,
-      default: false,
-      ...before?.public_limits === void 0 ? {} : { public_limits: before.public_limits }
-    };
+    return { port: Number(match[1]), access, default: false };
   });
 }
 function withDefault(ports, defaultPort) {
@@ -2493,6 +2664,42 @@ function parseEnv(pairs) {
   }
   return env;
 }
+var SECRET_LOOKING = /(_KEY|_TOKEN)$|SECRET|PASSWORD/i;
+function specWarnings(deps, ports, envKeys) {
+  if (ports.length === 0)
+    deps.notice(
+      "This Machine has no port: until exec and SSH arrive, nothing can wake it. Add --port <port>."
+    );
+  const secret = envKeys.filter((key) => SECRET_LOOKING.test(key)).sort();
+  if (secret.length)
+    deps.notice(
+      `${secret.join(", ")} ${secret.length === 1 ? "looks" : "look"} secret: env values are readable by every member through the API; Machine secrets come later.`
+    );
+}
+function waitTimeout(options) {
+  if (options.timeout !== void 0 && !options.wait) throw new Error("--timeout needs --wait.");
+  return options.timeout ?? DEFAULT_WAIT_SECONDS;
+}
+var DEFAULT_WAIT_SECONDS = 300;
+async function waitForMachine(deps, key, name, firstWait, timeout, settled) {
+  const now = deps.now ?? Date.now;
+  const pause = deps.pause ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const start = now();
+  let wait = firstWait;
+  let last = null;
+  for (; ; ) {
+    const elapsed = (now() - start) / 1e3;
+    if (elapsed + wait > timeout) return { machine: null, last, waited: Math.round(elapsed) };
+    await pause(wait * 1e3);
+    const machine = await deps.api.getMachine(key, name);
+    if (machine.kind === "byoc")
+      throw new Error(`${name} is one of your computers, not a Machine.`);
+    if (settled(machine))
+      return { machine, last: machine, waited: Math.round((now() - start) / 1e3) };
+    last = machine;
+    wait = pollAfterSeconds;
+  }
+}
 async function machineListCommand(deps, options = {}) {
   await machineCommand(async () => {
     const page = await deps.api.listMachines(await deps.auth.apiKey(), {
@@ -2542,47 +2749,146 @@ async function machineListCommand(deps, options = {}) {
 }
 function createdText(machine) {
   if (machine.state === "creating")
-    return `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready.`;
+    return `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready, or create with --wait.`;
   return `Created Machine ${machine.name}.`;
 }
+function ago(deps, timestamp) {
+  const seconds = Math.max(
+    0,
+    Math.round(((deps.now ?? Date.now)() - Date.parse(timestamp)) / 1e3)
+  );
+  if (seconds < 120) return `${seconds} s`;
+  if (seconds < 7200) return `${Math.round(seconds / 60)} min`;
+  if (seconds < 172800) return `${Math.round(seconds / 3600)} h`;
+  return `${Math.round(seconds / 86400)} days`;
+}
+async function nameTaken(deps, key, name, error) {
+  let holder;
+  try {
+    holder = await deps.api.getMachine(key, name);
+  } catch {
+    return error;
+  }
+  const what = holder.kind === "byoc" ? `${name} is one of your computers; choose another name.` : `A Machine named ${name} already exists (created ${ago(deps, holder.created_at)} ago, ${holder.state}); if it is yours from a lost reply, \`tonbo machine show ${name}\`.`;
+  return new HttpError(`${error.message}
+${what}`, error.status, error.body, error.requestId);
+}
+async function waitForCreate(deps, key, machine, name, firstWait, timeout, json) {
+  const {
+    machine: settled,
+    last,
+    waited
+  } = await waitForMachine(
+    deps,
+    key,
+    name,
+    firstWait,
+    timeout,
+    (read) => read.state !== "creating"
+  );
+  if (!settled) {
+    const known = last ?? machine;
+    print(deps, json, known, machineFields(known));
+    throw new Error(
+      `Machine ${machine.name} is still creating after ${waited} s; nothing was undone. \`tonbo machine show ${machine.name}\` reports it active when it is ready.`
+    );
+  }
+  if (settled.state === "active") {
+    const pulled = settled.image.digest === null ? "" : `, image ${settled.image.state}`;
+    print(
+      deps,
+      json,
+      settled,
+      [
+        `Created ${settled.name} in ${settled.region} (active after ${waited} s${pulled}).`,
+        machineText(settled)
+      ].join("\n")
+    );
+    return;
+  }
+  print(deps, json, settled, machineFields(settled));
+  if (settled.state === "failed") {
+    const { reason, hint } = creationFailureText(settled);
+    throw new Error(
+      `Machine ${settled.name} failed to be created${reason}; delete it with \`tonbo machine delete ${settled.name}\` and create it again.${hint}`
+    );
+  }
+  throw new Error(`Machine ${settled.name} is ${settled.state}; it was not created.`);
+}
 async function machineCreateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (!options.image) throw new Error("Pass --image <reference>.");
+    const timeout = waitTimeout(options);
     const env = parseEnv(options.env ?? []);
-    const ports = withDefault(parsePorts(options.port ?? [], []), options.defaultPort);
+    const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
     const shape = options.shape ?? (await deps.api.listMachineShapes(key)).default;
-    const machine = await deps.api.createMachine(
-      key,
-      {
-        name,
-        image: options.image,
-        shape,
-        region: options.region,
-        command: command.length ? command : void 0,
-        ports: ports.length ? ports : void 0,
-        env: Object.keys(env).length ? env : void 0,
-        sleep_after_seconds: options.sleepAfter,
-        idle_action: options.idleAction,
-        stop_grace_seconds: options.stopGrace
-      },
-      options.idempotencyKey ?? randomUUID3()
-    );
+    let created;
+    try {
+      created = await deps.api.createMachine(
+        key,
+        {
+          name,
+          image: options.image,
+          shape,
+          region: options.region,
+          command: command.length ? command : void 0,
+          ports: ports.length ? ports : void 0,
+          env: Object.keys(env).length ? env : void 0,
+          sleep_after_seconds: options.sleepAfter,
+          idle_action: options.idleAction,
+          stop_grace_seconds: options.stopGrace
+        },
+        options.idempotencyKey ?? randomUUID3()
+      );
+    } catch (error) {
+      if (error instanceof HttpError && error.code === "name_taken")
+        throw await nameTaken(deps, key, name, error);
+      throw error;
+    }
+    const { machine } = created;
+    specWarnings(deps, machine.ports, Object.keys(env));
     if (machine.state === "failed") {
       print(deps, options.json, machine, machineFields(machine));
+      const { reason, hint } = creationFailureText(machine);
       throw new Error(
-        `Machine ${machine.name} failed to be created; delete it with \`tonbo machine delete ${machine.name}\` and create it again.`
+        `Machine ${machine.name} failed to be created${reason}; delete it with \`tonbo machine delete ${machine.name}\` and create it again.${hint}`
       );
     }
-    print(deps, options.json, machine, [createdText(machine), machineFields(machine)].join("\n"));
+    if (options.wait && machine.state === "creating")
+      return waitForCreate(
+        deps,
+        key,
+        machine,
+        deps.api.machineNameAt(created.location) ?? machine.name,
+        created.retryAfterSeconds ?? pollAfterSeconds,
+        timeout,
+        options.json
+      );
+    print(deps, options.json, machine, [createdText(machine), machineText(machine)].join("\n"));
   });
 }
 async function machineShowCommand(deps, name, options = {}) {
   await machineCommand(async () => {
-    const machine = await deps.api.getMachine(await deps.auth.apiKey(), name);
-    print(deps, options.json, machine, anyMachineFields(machine));
+    const { machine, etag } = await deps.api.getMachineWithEtag(await deps.auth.apiKey(), name);
+    print(deps, options.json, machine, anyMachineText(machine, etag));
   });
 }
+function appliesText(name, change) {
+  const lines = [];
+  if (change.ports !== void 0 || change.sleep_after_seconds !== void 0)
+    lines.push("Ports and sleep-after apply now.");
+  const later = [change.image, change.command, change.shape, change.env].some(
+    (field) => field !== void 0
+  );
+  if (later) {
+    lines.push(
+      `The change applies at the next activation. To apply it now, run \`tonbo machine sleep ${name}\`; the next request boots the new spec.`
+    );
+    if (change.image !== void 0) lines.push("Naming the same tag again re-resolves its digest.");
+  }
+  return lines;
+}
 async function machineUpdateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (command.length && options.imageCommand)
@@ -2590,12 +2896,14 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
     if (options.clearPorts && (options.port?.length || options.defaultPort !== void 0))
       throw new Error("Give --port or --clear-ports, not both.");
     const key = await deps.auth.apiKey();
-    const read = await deps.api.getMachine(key, name);
+    const { machine: read, etag: readTag } = await deps.api.getMachineWithEtag(key, name);
     if (read.kind === "byoc")
       throw new Error(
         `${name} is one of your computers; only \`tonbo machine show\` and \`tonbo machine delete\` serve it.`
       );
     const current = read;
+    const etag = ifMatchHeader(options.ifMatch) ?? readTag;
+    if (etag === null) throw new Error(`The API answered ${name} without an ETag.`);
     const change = {
       image: options.image,
       shape: options.shape,
@@ -2606,59 +2914,90 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
     };
     if (options.clearPorts) change.ports = [];
     else if (options.port?.length) {
-      const ports = parsePorts(options.port, current.ports);
+      const ports = parsePorts(options.port);
       const kept = current.ports.find((entry) => entry.default)?.port;
       const defaultPort = options.defaultPort ?? (ports.some((entry) => entry.port === kept) ? kept : void 0);
       change.ports = withDefault(ports, defaultPort);
     } else if (options.defaultPort !== void 0)
       change.ports = withDefault(current.ports, options.defaultPort);
+    const setEnv = parseEnv(options.env ?? []);
     if (options.env?.length || options.unsetEnv?.length) {
-      const env = { ...current.env, ...parseEnv(options.env ?? []) };
+      const env = { ...current.env, ...setEnv };
       for (const variable of options.unsetEnv ?? []) delete env[variable];
       change.env = env;
     }
     if (options.discardSnapshot) change.discard_snapshot = true;
     if (Object.values(change).every((value) => value === void 0))
       throw new Error("Nothing to change: pass at least one option or a command.");
-    const machine = await deps.api.updateMachine(
-      key,
-      name,
-      options.revision ?? current.revision,
-      change
-    );
+    const machine = await deps.api.updateMachine(key, name, etag, change);
+    specWarnings(deps, machine.ports, Object.keys(setEnv));
     print(
       deps,
       options.json,
       machine,
       [
-        `Updated Machine ${machine.name} to revision ${machine.revision}. Ports and sleep-after apply now; image, command, shape and env at its next boot.`,
-        machineFields(machine)
+        `Updated Machine ${machine.name} to revision ${machine.revision}.`,
+        ...appliesText(machine.name, change),
+        machineText(machine)
       ].join("\n")
     );
   });
 }
+function sleptText(machine) {
+  if (machine.state === "creating")
+    return `Machine ${machine.name} is still creating; nothing to put to sleep.`;
+  if (machine.status.power === "asleep")
+    return `Machine ${machine.name} is already asleep; nothing to do. The next request boots it.`;
+  return `Machine ${machine.name} is going to sleep (${machine.status.sleep.action}); the next request boots it again, on its latest spec.`;
+}
 async function machineSleepCommand(deps, name, options = {}) {
   await machineCommand(async () => {
-    const machine = await deps.api.sleepMachine(await deps.auth.apiKey(), name);
+    const timeout = waitTimeout(options);
+    const key = await deps.auth.apiKey();
+    const machine = await deps.api.sleepMachine(key, name, ifMatchHeader(options.ifMatch));
+    const going = options.wait && machine.state === "active" && machine.status.power !== "asleep";
+    if (!going) {
+      print(deps, options.json, machine, sleptText(machine));
+      return;
+    }
+    const { machine: asleep, waited } = await waitForMachine(
+      deps,
+      key,
+      name,
+      pollAfterSeconds,
+      timeout,
+      (read) => read.status.power === "asleep" || read.state !== "active"
+    );
+    if (!asleep)
+      throw new Error(
+        `Machine ${name} is not asleep after ${waited} s; \`tonbo machine show ${name}\` says what keeps it awake.`
+      );
+    if (asleep.status.power !== "asleep")
+      throw new Error(`Machine ${name} is ${asleep.state}; it did not go to sleep.`);
     print(
       deps,
       options.json,
-      machine,
-      `Machine ${machine.name} is going to sleep (${machine.status.sleep.action}); its next connection wakes it.`
+      asleep,
+      `Machine ${asleep.name} is asleep (after ${waited} s); the next request boots it, on its latest spec.`
     );
   });
 }
 async function machineDeleteCommand(deps, name, options = {}) {
   await machineCommand(async () => {
     const key = await deps.auth.apiKey();
+    const read = { etag: null };
     await confirm(
       deps,
       options.yes,
       `delete Machine ${name}`,
-      () => deleteQuestion(deps, key, name),
+      () => deleteQuestion(deps, key, name, read),
       name
     );
-    const { machine, kind } = await deps.api.deleteMachine(key, name);
+    const { machine, kind } = await deps.api.deleteMachine(
+      key,
+      name,
+      ifMatchHeader(options.ifMatch) ?? read.etag ?? void 0
+    );
     print(deps, options.json, machine, deletedText(name, machine, kind));
     if (machine?.kind === "byoc" && machine.byoc.key_state === "active")
       deps.notice(
@@ -2666,10 +3005,12 @@ async function machineDeleteCommand(deps, name, options = {}) {
       );
   });
 }
-async function deleteQuestion(deps, key, name) {
+async function deleteQuestion(deps, key, name, read) {
   let kind = null;
   try {
-    kind = (await deps.api.getMachine(key, name)).kind;
+    const answer = await deps.api.getMachineWithEtag(key, name);
+    kind = answer.machine.kind;
+    read.etag = answer.etag;
   } catch (error) {
     if (!(error instanceof HttpError && error.status === 404)) throw error;
   }
@@ -2686,6 +3027,9 @@ function deletedText(name, machine, kind) {
     return `Machine ${machine.name} is being deleted; its name is free for a new Machine.`;
   return `Released the name ${name}; no Machine had been created under it.`;
 }
+function hourlyPrice(micros) {
+  return `$${(micros / 1e6).toFixed(4)}/h`;
+}
 async function machineShapesCommand(deps, options = {}) {
   await machineCommand(async () => {
     const shapes = await deps.api.listMachineShapes(await deps.auth.apiKey());
@@ -2694,14 +3038,15 @@ async function machineShapesCommand(deps, options = {}) {
       options.json,
       shapes,
       table(
-        ["SHAPE", "VCPUS", "MEMORY", "SCRATCH", "OFFERED", "SUSPENDABLE"],
+        ["SHAPE", "VCPUS", "MEMORY", "SCRATCH", "OFFERED", "SUSPENDABLE", "LIST PRICE"],
         shapes.data.map((shape) => [
           shape.shape === shapes.default ? `${shape.shape} (default)` : shape.shape,
           String(shape.vcpus),
           `${shape.memory_gib} GiB`,
           `${shape.scratch_gib} GiB`,
           shape.offered ? "yes" : "no",
-          shape.suspendable ? "yes" : "no"
+          shape.suspendable ? "yes" : "no",
+          hourlyPrice(shape.ceiling_usd_micros_per_hour)
         ])
       )
     );
@@ -2768,6 +3113,7 @@ function operationOptions(command, operationId) {
     command.option("--cursor <cursor>", "continue from the cursor a previous page printed");
   return command.option("--json", "print the API data as JSON");
 }
+var ifMatchHelp = (action) => `${action} only the Machine at the ETag \`tonbo machine show\` printed (with or without its quotes); the ETag the command reads, if it reads one, by default`;
 var repeated = (value, previous = []) => [...previous, value];
 var roleOption = (description) => new Option("--role <role>", description).choices(accountRoles);
 function machineSpecOptions(command, update) {
@@ -3075,6 +3421,10 @@ function createProgram(dependencies = createDependencies) {
     ).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; ${DEFAULT_WAIT_SECONDS} by default`,
+      parseWhole
     ),
     "createMachine"
   ).action(
@@ -3090,11 +3440,7 @@ function createProgram(dependencies = createDependencies) {
     machineSpecOptions(
       machine.command("update <name> [command...]").description(
         "change a Machine; [command...] after -- replaces its command at the next boot"
-      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option(
-        "--revision <revision>",
-        "write only if the Machine is still at this revision (tonbo machine show); the revision it reads by default",
-        parseWhole
-      ).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
+      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
       true
     ),
     "updateMachine"
@@ -3102,7 +3448,11 @@ function createProgram(dependencies = createDependencies) {
     async (name, command, options) => machineUpdateCommand(dependencies(), name, command, options)
   );
   operationOptions(
-    machine.command("sleep <name>").description("put a Machine to sleep now"),
+    machine.command("sleep <name>").description("put a Machine to sleep now; its next request boots it on its latest spec").option("--if-match <etag>", ifMatchHelp("put to sleep")).option("--wait", "wait until the Machine is asleep").option(
+      "--timeout <seconds>",
+      `how long --wait waits; ${DEFAULT_WAIT_SECONDS} by default`,
+      parseWhole
+    ),
     "sleepMachine"
   ).action(
     async (name, options) => machineSleepCommand(dependencies(), name, options)
@@ -3110,7 +3460,7 @@ function createProgram(dependencies = createDependencies) {
   operationOptions(
     machine.command("delete <name>").description(
       "delete a Machine with its disk, database and logs, or forget one of your computers"
-    ).option("--yes", "delete without asking; required when stdin is not a terminal"),
+    ).option("--yes", "delete without asking; required when stdin is not a terminal").option("--if-match <etag>", ifMatchHelp("delete")),
     "deleteMachine"
   ).action(
     async (name, options) => machineDeleteCommand(dependencies(), name, options)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The Tonbo CLI: sign in and manage account resources from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {