@astris-labs/cli 0.1.2 → 0.1.4

package/README.md

@@ -30,7 +30,7 @@ Requests go to `https://api.astris.run`.
 
 ## Commands
 
-v0 commands are `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `list`, `logs`, `usage`, `plans`, `whoami`, `login`, `logout`, `app`, `preflight`, and `export`.
+v0 commands are `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `compose`, `list`, `logs`, `usage`, `plans`, `whoami`, `next`, `login`, `logout`, `app`, `preflight`, and `export`.
 
 `--json` writes one JSON object to stdout. Without `--json`, success is text on stdout and an error is a sentence on stderr.
 
@@ -93,6 +93,18 @@ Optional flags are `--build-path`, `--dockerfile`, `--port`, `--build`, `--publi
 
 `astris database delete --id <id> --yes` calls `DELETE /v1/databases/:id` and sends no body. Without `--yes` it makes no request and says the database and its data are removed and that `--yes` confirms. A repeated `--id` is refused and makes no request. Human output is `Database removed.` `--json` prints one JSON object `{"database_id":"<id>","removed":true}`.
 
+### compose
+
+`astris compose list` calls `GET /v1/compose`. Human output is one line per stack in the order the API returned: the id, the name, and the project name. An empty list prints nothing. `--json` prints one JSON object `{"compose":[...]}` of the stack rows.
+
+`astris compose deploy --id <id>` calls `POST /v1/compose/:id/deploy` and sends no body. In the private preview the API refuses every redeploy, so the command prints the API's sentence and exits 1. Otherwise human output is the stack id, project id, name, git URL, branch, compose path, memory limit, created_at, and updated_at, one per line. `--json` prints one JSON object `{"compose":{...}}`.
+
+`astris compose start --id <id>` calls `POST /v1/compose/:id/start` and sends no body. Human output is the status the API returned, then the same stack fields as deploy, one per line. `--json` prints one JSON object `{"compose":{...},"status":"<status>"}`.
+
+`astris compose stop --id <id>` calls `POST /v1/compose/:id/stop` and sends no body. Human output matches start. `--json` prints one JSON object `{"compose":{...},"status":"<status>"}`.
+
+Without `--id`, or with an id that is not a stack id, deploy, start, and stop make no request and say `Send --id set to the compose stack id.`
+
 ### storage
 
 `astris storage create --name <name>` calls `POST /v1/buckets` with `name` after trim. Human output is the bucket id, the name, the endpoint, the bucket, the access key id, and the secret key, one value per line. The secret key is printed on this command only, so save it now. `--json` prints one JSON object of the response body: the bucket row and the credentials.
@@ -125,6 +137,10 @@ When storage is not configured, all four commands print `Storage is not availabl
 
 `astris whoami` calls `GET /v1/me`. It takes no flags besides `--json`. `--json` prints the account id, email, status, plan, and created_at, and the key id, name, and key_prefix. Human output is three lines: `Account: <email>`, `Plan: <plan>` (`Plan: none` when plan is null), and `Key: <name> (<key_prefix>)`.
 
+### next
+
+`astris next` prints this account's next step as one sentence. `--json` prints `{step, sentence}`.
+
 ### login
 
 `astris login` takes no key as an argument. On a terminal it asks `Paste your Astris API key:` and does not show what is typed. With a pipe it reads the key from stdin. When the API accepts the key, it writes `Logged in.`
@@ -160,18 +176,22 @@ Exit code 0 means the command succeeded. Any error exits with a non-zero code. W
 
 Some arguments are refused on this machine, before any request.
 
-The command name is checked first. The words `help`, `--help`, and `-h` print the usage and the command names, exit 0, and make no request. `deploy`, `status`, `env`, `domains`, `restart`, `logs`, `rollback`, `diagnose`, `database`, `storage`, `list`, `usage`, `plans`, `whoami`, `login`, `logout`, `app`, `preflight`, and `export` are known. Any other name writes `Unknown command.` and makes no request.
+The command name is checked first. The words `help`, `--help`, and `-h` print the usage and the command names, exit 0, and make no request. `deploy`, `status`, `env`, `domains`, `restart`, `logs`, `rollback`, `diagnose`, `database`, `storage`, `compose`, `list`, `usage`, `plans`, `whoami`, `next`, `login`, `logout`, `app`, `preflight`, and `export` are known. Any other name writes `Unknown command.` and makes no request.
 
 Login asks for the key on a terminal and reads it from stdin otherwise. Logout deletes that one file. Every other known command uses this sentence: When `ASTRIS_API_KEY` is set to a non-empty value, that value is the key, and the saved file is used only when the variable is missing or empty. A missing or empty variable and a missing or empty file write `ASTRIS_API_KEY is not set` to stderr and make no request. That is also true when `--json` is set.
 
 `login` and `logout` take no arguments. An argument is refused, and `logout` does not delete the file.
 
-After the key, `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, and `storage` refuse a flag they do not know, a flag with no value, and a bare word that is not a flag. The sentence is `Those arguments were refused. Check the flags and send them again.`
+After the key, `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `compose`, and `next` refuse a flag they do not know, a flag with no value, and a bare word that is not a flag. The sentence is `Those arguments were refused. Check the flags and send them again.`
 
 `diagnose` requires `--app` set to an application id, the same check as `status`. `database` takes one word, `create`, `status`, `backup`, or `delete`. `create` requires `--project`, `--kind`, and `--name`. `--project` is a project id. `--kind` is exactly `postgres` or `redis`. `status` and `backup` each require `--id` set to a database id. `backup` is accepted. `delete` requires `--id` set to a database id and `--yes`, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. The plural `backups` is refused and makes no request.
 
 `storage` takes one word, `create`, `list`, `show`, or `delete`. `create` requires `--name`. `show` and `delete` each require `--id` set to a bucket id, and a `--id` that is not a bucket id makes no request. `delete` requires `--yes`, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. `list` takes no word, so `storage list buckets` is refused and makes no request.
 
+`compose` takes one word, `list`, `deploy`, `start`, or `stop`. `deploy`, `start`, and `stop` each require `--id` set to a compose stack id, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. `list` rejects `--id`.
+
+`next` takes no word and no flag besides `--json`.
+
 `domains` binds with no word, or verifies with the one word `verify`. `--hostname` with `--slug` is refused. An empty `--hostname`, or one containing a space, is refused before any request. Other hostname rules are left to the API. `verify` requires `--app` set to an application id and `--id` set to a domain id; a missing or non-UUID `--id`, and a word other than `verify`, make no request.
 
 `--app` is refused unless the value, after trim, is an id of eight, four, four, four, and twelve hexadecimal digits, with hyphens, in either case. The sentence is `Send --app set to the application id.` `status`, `env`, `domains`, and `restart` require that id. `deploy` requires it when `--app` is present or when `--hook` is sent (`--hook` without `--app` is refused with `Send --app set to the application id.`), and then refuses `--build`, `--publish-directory`, `--spa`, `--kind`, `--command`, and `--schedule`; the other create flags are ignored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astris-labs/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The Astris CLI, a command-line client of the Astris API.",
   "repository": {
     "type": "git",

package/src/client.mjs

@@ -18,6 +18,22 @@ function swallow(promise) {
   promise.catch(() => undefined);
 }
 
+function retryAfterSecondsOf(headers) {
+  if (!headers) return null;
+  let raw;
+  if (typeof headers.get === "function") {
+    raw = headers.get("retry-after");
+  } else if (typeof headers === "object") {
+    raw = headers["retry-after"] ?? headers["Retry-After"];
+  }
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!/^[0-9]+$/.test(trimmed)) return null;
+  const seconds = Number(trimmed);
+  if (seconds < 1 || seconds > 3600) return null;
+  return seconds;
+}
+
 export async function astrisFetch({ key, baseUrl, path, method, body, fetchImpl }) {
   const url = baseUrl + path;
   const headers = { Authorization: `Bearer ${key}` };
@@ -54,14 +70,15 @@ export async function astrisFetch({ key, baseUrl, path, method, body, fetchImpl
     }
     swallow(reading);
     const text = await Promise.race([reading, timeout]);
+    const retryAfterSeconds = retryAfterSecondsOf(response?.headers);
 
     if (text === "") {
-      return { status: response.status, body: null };
+      return { status: response.status, body: null, retryAfterSeconds };
     }
     try {
-      return { status: response.status, body: JSON.parse(text) };
+      return { status: response.status, body: JSON.parse(text), retryAfterSeconds };
     } catch {
-      return { status: response.status, body: null };
+      return { status: response.status, body: null, retryAfterSeconds };
     }
   } catch (err) {
     throw new Error(redact(failureMessage(err), key));

package/src/commands.mjs

@@ -16,6 +16,7 @@ const SENTENCE = {
   projectId: "Send --project set to the project id.",
   databaseFlags: "Those arguments were refused. Send --project, --kind, and --name.",
   databaseId: "Send --id set to the database id.",
+  composeId: "Send --id set to the compose stack id.",
   domainId: "Send --id set to the domain id.",
   git: "The Git URL must not include a user name or password.",
   // T-169: reused word for word from the MCP's SENTENCE.deployKey (T-139).
@@ -57,16 +58,26 @@ const HTTP_SENTENCE = new Map([
   [401, SENTENCE.unauthorized],
   [404, SENTENCE.notFound],
   [409, SENTENCE.taken],
+  [429, "This account asked for too many changes in a short time. Wait a little, then try again."],
   [502, SENTENCE.platform],
 ]);
 
-function sentenceFor(status) {
+function rateWaitSentence(seconds) {
+  if (typeof seconds === "number") {
+    return `This account asked for too many changes in a short time. Wait ${seconds} second${seconds === 1 ? "" : "s"}, then try again.`;
+  }
+  return "This account asked for too many changes in a short time. Wait a little, then try again.";
+}
+
+function sentenceFor(status, retryAfterSeconds = null) {
+  if (status === 429) return rateWaitSentence(retryAfterSeconds);
   return HTTP_SENTENCE.get(status) ?? SENTENCE.failed;
 }
 
-function errorMessage(status, body) {
+function errorMessage(status, body, retryAfterSeconds = null) {
+  if (status === 429) return rateWaitSentence(retryAfterSeconds);
   if (isRecord(body) && typeof body.message === "string") return body.message;
-  return sentenceFor(status);
+  return sentenceFor(status, retryAfterSeconds);
 }
 
 function upgradeMessage(status, body) {
@@ -76,6 +87,14 @@ function upgradeMessage(status, body) {
   return body.message;
 }
 
+// T-275: the API pauses compose redeploy in the private preview and says why.
+function composeUnavailableMessage(status, body) {
+  if (status !== 403 || !isRecord(body) || body.error !== "compose_unavailable" || typeof body.message !== "string") {
+    return null;
+  }
+  return body.message;
+}
+
 function storageCreateMessage(status, body) {
   if (!isRecord(body)) return null;
   if (status === 403 && body.error === "bucket_limit") {
@@ -331,7 +350,7 @@ async function redeploy(io, key, json, appId) {
     method: "POST",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 202) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 202) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const application = result.body?.application ?? {};
   const id = text(application.id) || appId;
   const name = text(application.name);
@@ -443,7 +462,7 @@ async function createThenDeploy(io, key, json, flags) {
   try {
     const listed = await call(io, key, { path: "/v1/projects", method: "GET" });
     if (listed.network) return fail(io, key, json, SENTENCE.platform, created);
-    if (listed.status !== 200) return fail(io, key, json, sentenceFor(listed.status), created);
+    if (listed.status !== 200) return fail(io, key, json, sentenceFor(listed.status, listed.retryAfterSeconds), created);
     let projectId = findProjectId(listed.body, project);
     if (projectId === null) {
       const made = await call(io, key, {
@@ -454,7 +473,7 @@ async function createThenDeploy(io, key, json, flags) {
       if (made.network) return fail(io, key, json, SENTENCE.platform, created);
       const madeId = made.body?.project?.id;
       if (made.status !== 201 || typeof madeId !== "string" || madeId === "") {
-        return fail(io, key, json, made.status === 201 ? SENTENCE.failed : sentenceFor(made.status), created);
+        return fail(io, key, json, made.status === 201 ? SENTENCE.failed : sentenceFor(made.status, made.retryAfterSeconds), created);
       }
       projectId = madeId;
       created.projectId = madeId;
@@ -482,7 +501,7 @@ async function createThenDeploy(io, key, json, flags) {
         io,
         key,
         json,
-        passed ?? (madeApp.status === 201 ? SENTENCE.failed : sentenceFor(madeApp.status)),
+        passed ?? (madeApp.status === 201 ? SENTENCE.failed : sentenceFor(madeApp.status, madeApp.retryAfterSeconds)),
         created,
       );
     }
@@ -516,7 +535,7 @@ async function createThenDeploy(io, key, json, flags) {
       method: "POST",
     });
     if (deployed.network) return fail(io, key, json, SENTENCE.platform, created);
-    if (deployed.status !== 202) return fail(io, key, json, sentenceFor(deployed.status), created);
+    if (deployed.status !== 202) return fail(io, key, json, sentenceFor(deployed.status, deployed.retryAfterSeconds), created);
     const shown = deployed.body?.application ?? application;
     const id = text(shown.id) || applicationId;
     const shownName = text(shown.name) || name;
@@ -575,7 +594,7 @@ export async function status(args, io) {
     method: "GET",
   });
   if (result.network) return fail(io, opened.key, opened.json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status, result.retryAfterSeconds));
   const statusText = text(result.body?.status);
   const hostnames = hostnamesOf(result.body);
   const id = text(result.body?.application?.id) || required.appId;
@@ -601,7 +620,7 @@ async function hookUrl(io, key, json, appId) {
     method: "GET",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const url = result.body?.hook?.url;
   if (typeof url !== "string") return fail(io, key, json, SENTENCE.failed);
   return succeed(io, key, json, { application_id: appId, url }, `${url}\n`);
@@ -615,7 +634,7 @@ async function envNames(io, key, json, appId) {
     method: "GET",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const names = result.body?.names;
   if (!Array.isArray(names) || !names.every((name) => typeof name === "string")) {
     return fail(io, key, json, SENTENCE.failed);
@@ -643,7 +662,7 @@ export async function env(args, io) {
     body,
   });
   if (result.network) return fail(io, opened.key, opened.json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status, result.retryAfterSeconds));
   return succeed(
     io,
     opened.key,
@@ -739,7 +758,7 @@ async function domainsBind(args, io, key) {
   }
   const result = await call(io, key, request);
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 201) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 201) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const domain = isRecord(result.body) ? result.body.domain : undefined;
   const hostname = text(domain?.hostname);
   if (hostnameFlag === undefined) {
@@ -777,7 +796,7 @@ async function domainsVerify(args, io, key) {
     method: "POST",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const body = isRecord(result.body) ? result.body : {};
   const domain = isRecord(body.domain) ? body.domain : {};
   const statusText = typeof domain.status === "string" ? domain.status : "";
@@ -810,7 +829,7 @@ export async function restart(args, io) {
     method: "POST",
   });
   if (result.network) return fail(io, opened.key, opened.json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, opened.key, opened.json, sentenceFor(result.status, result.retryAfterSeconds));
   return succeed(
     io,
     opened.key,
@@ -861,7 +880,7 @@ export async function logs(args, io) {
     method: "GET",
   });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   if (!isRecord(result.body) || typeof result.body.lines !== "string") {
     return fail(io, loaded.key, json, SENTENCE.failed);
   }
@@ -925,7 +944,7 @@ export async function list(args, io) {
     resource === "apps" ? "/v1/apps" : resource === "databases" ? "/v1/databases" : "/v1/projects";
   const result = await call(io, loaded.key, { path, method: "GET" });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   if (resource !== "projects") {
     const human = listText(resource, result.body);
     if (human === null) return fail(io, loaded.key, json, SENTENCE.failed);
@@ -962,7 +981,7 @@ export async function usage(args, io) {
   const json = parsed.values.json === true;
   const result = await call(io, loaded.key, { path: "/v1/usage", method: "GET" });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const human = usageText(result.body);
   if (human === null) return fail(io, loaded.key, json, SENTENCE.failed);
   return succeed(io, loaded.key, json, result.body, human);
@@ -992,7 +1011,7 @@ export async function plans(args, io) {
   const json = parsed.values.json === true;
   const result = await call(io, loaded.key, { path: "/v1/plans", method: "GET" });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const human = plansText(result.body);
   if (human === null) return fail(io, loaded.key, json, SENTENCE.failed);
   return succeed(io, loaded.key, json, result.body, human);
@@ -1041,7 +1060,7 @@ export async function whoami(args, io) {
   const json = parsed.values.json === true;
   const result = await call(io, loaded.key, { path: "/v1/me", method: "GET" });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const view = whoamiView(result.body);
   if (view === null) return fail(io, loaded.key, json, SENTENCE.failed);
   const plan = view.account.plan === null ? "none" : view.account.plan;
@@ -1182,7 +1201,7 @@ export async function diagnose(args, io) {
     method: "GET",
   });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const human = diagnoseSentences(result.body);
   if (human === null) return fail(io, loaded.key, json, SENTENCE.failed);
   return succeed(io, loaded.key, json, result.body, human);
@@ -1210,7 +1229,7 @@ async function databaseCreate(args, io, key) {
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
   if (result.status !== 201) {
-    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status));
+    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status, result.retryAfterSeconds));
   }
   const view = databaseFields(isRecord(result.body) ? result.body.database : null);
   const password = isRecord(result.body) ? result.body.password : undefined;
@@ -1233,7 +1252,7 @@ async function databaseStatus(args, io, key) {
     method: "GET",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const view = databaseFields(isRecord(result.body) ? result.body.database : null);
   const statusText = isRecord(result.body) ? result.body.status : undefined;
   if (view === null || typeof statusText !== "string") return fail(io, key, json, SENTENCE.failed);
@@ -1269,7 +1288,7 @@ async function databaseBackup(args, io, key) {
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
   if (result.status === 409) return fail(io, key, json, SENTENCE.noBackup);
-  if (result.status !== 202) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 202) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   return succeed(io, key, json, { database_id: id, backup: "run" }, "Backup run.\n");
 }
 
@@ -1289,7 +1308,7 @@ async function databaseDelete(args, io, key) {
     method: "DELETE",
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
-  if (result.status !== 204) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 204) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   return succeed(io, key, json, { database_id: id, removed: true }, "Database removed.\n");
 }
 
@@ -1396,7 +1415,7 @@ async function storageCreate(args, io, key) {
   if (refusal !== null) return fail(io, key, json, refusal);
   if (result.status === 503) return fail(io, key, json, SENTENCE.storageOff);
   if (result.status !== 201) {
-    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status));
+    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status, result.retryAfterSeconds));
   }
   const body = isRecord(result.body) ? result.body : null;
   const view = body === null ? null : storageFields(body.bucket);
@@ -1438,7 +1457,7 @@ async function storageList(args, io, key) {
   const result = await call(io, key, { path: "/v1/buckets", method: "GET" });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
   if (result.status === 503) return fail(io, key, json, SENTENCE.storageOff);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const items = isRecord(result.body) && Array.isArray(result.body.buckets) ? result.body.buckets : null;
   if (items === null) return fail(io, key, json, SENTENCE.failed);
   const views = [];
@@ -1465,7 +1484,7 @@ async function storageShow(args, io, key) {
   });
   if (result.network) return fail(io, key, json, SENTENCE.platform);
   if (result.status === 503) return fail(io, key, json, SENTENCE.storageOff);
-  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   const view = storageFields(isRecord(result.body) ? result.body.bucket : null);
   if (view === null) return fail(io, key, json, SENTENCE.failed);
   return succeed(io, key, json, { bucket: view }, `${storageLines(view).join("\n")}\n`);
@@ -1489,7 +1508,7 @@ async function storageDelete(args, io, key) {
   if (result.network) return fail(io, key, json, SENTENCE.platform);
   if (result.status === 409) return fail(io, key, json, SENTENCE.bucketNotEmpty);
   if (result.status === 503) return fail(io, key, json, SENTENCE.storageOff);
-  if (result.status !== 204) return fail(io, key, json, sentenceFor(result.status));
+  if (result.status !== 204) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
   return succeed(io, key, json, { bucket_id: id, removed: true }, `${SENTENCE.bucketRemoved}\n`);
 }
 
@@ -1523,7 +1542,7 @@ export async function login(args, io) {
   if (key === "") return fail(io, "", false, SENTENCE.emptyKey);
   const result = await call(io, key, { path: "/v1/me", method: "GET" });
   if (result.network) return fail(io, key, false, SENTENCE.platform);
-  if (result.status !== 200) return fail(io, key, false, sentenceFor(result.status));
+  if (result.status !== 200) return fail(io, key, false, sentenceFor(result.status, result.retryAfterSeconds));
   saveApiKey(io.env, key);
   io.stdout.write(`${SENTENCE.loggedIn}\n`);
   return { exitCode: 0 };
@@ -1577,7 +1596,7 @@ async function appRemove(args, io, key) {
 
   const got = await call(io, key, { path: `/v1/apps/${encodeURIComponent(appId)}`, method: "GET" });
   if (got.network) return fail(io, key, json, SENTENCE.platform);
-  if (got.status !== 200) return fail(io, key, json, sentenceFor(got.status));
+  if (got.status !== 200) return fail(io, key, json, sentenceFor(got.status, got.retryAfterSeconds));
   if (!isRecord(got.body)) return fail(io, key, json, SENTENCE.failed);
   const application = isRecord(got.body.application) ? got.body.application : null;
   if (application === null) return fail(io, key, json, SENTENCE.failed);
@@ -1591,7 +1610,7 @@ async function appRemove(args, io, key) {
 
   const deleted = await call(io, key, { path: `/v1/apps/${encodeURIComponent(appId)}`, method: "DELETE" });
   if (deleted.network) return fail(io, key, json, SENTENCE.platform);
-  if (deleted.status !== 200) return fail(io, key, json, sentenceFor(deleted.status));
+  if (deleted.status !== 200) return fail(io, key, json, sentenceFor(deleted.status, deleted.retryAfterSeconds));
   return succeed(io, key, json, { app_id: appId, removed: true }, `${SENTENCE.appRemoved}\n`);
 }
 
@@ -1749,7 +1768,7 @@ export async function preflight(args, io) {
   });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform, undefined, 2);
   if (result.status < 200 || result.status >= 300) {
-    return fail(io, loaded.key, json, errorMessage(result.status, result.body), undefined, 2);
+    return fail(io, loaded.key, json, errorMessage(result.status, result.body, result.retryAfterSeconds), undefined, 2);
   }
 
   if (
@@ -1815,7 +1834,7 @@ export async function accountExport(args, io) {
   });
   if (result.network) return fail(io, loaded.key, json, SENTENCE.platform, undefined, 2);
   if (result.status < 200 || result.status >= 300) {
-    return fail(io, loaded.key, json, errorMessage(result.status, result.body), undefined, 2);
+    return fail(io, loaded.key, json, errorMessage(result.status, result.body, result.retryAfterSeconds), undefined, 2);
   }
 
   if (json) {
@@ -1826,3 +1845,201 @@ export async function accountExport(args, io) {
   writeStdout(io, loaded.key, `${SENTENCE.exportAccepted}\n`);
   return { exitCode: 0 };
 }
+
+const NEXT_OPTIONS = {
+  json: { type: "boolean" },
+};
+
+export async function next(args, io) {
+  const loaded = loadKey(io);
+  if (loaded.exit) return loaded.exit;
+  const parsed = parseStrict(args, NEXT_OPTIONS, false);
+  if (parsed === null || parsed.positionals.length > 0) {
+    return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const result = await call(io, loaded.key, { path: "/v1/me/next-step", method: "GET" });
+  if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status, result.retryAfterSeconds));
+  const body = isRecord(result.body) ? result.body : null;
+  const step = body?.step;
+  const sentence = body?.sentence;
+  if (typeof step !== "string" || typeof sentence !== "string") {
+    return fail(io, loaded.key, json, SENTENCE.failed);
+  }
+  if (json) return succeed(io, loaded.key, json, { step, sentence }, "");
+  return succeed(io, loaded.key, json, { step, sentence }, `${sentence}\n`);
+}
+
+const COMPOSE_LIST_OPTIONS = {
+  json: { type: "boolean" },
+};
+
+const COMPOSE_ACTION_OPTIONS = {
+  json: { type: "boolean" },
+  id: { type: "string", multiple: true },
+};
+
+const COMPOSE_UNION = {
+  json: { type: "boolean" },
+  id: { type: "string" },
+};
+
+function composePositionals(args) {
+  try {
+    return parseArgs({
+      args: Array.isArray(args) ? args : [],
+      strict: false,
+      allowPositionals: true,
+      options: COMPOSE_UNION,
+    }).positionals;
+  } catch {
+    return null;
+  }
+}
+
+function composeFields(value) {
+  if (!isRecord(value)) return null;
+  const id = value.id;
+  const projectId = value.project_id;
+  const name = value.name;
+  const gitUrl = value.git_url;
+  const branch = value.branch;
+  const composePath = value.compose_path;
+  const memoryLimit = value.memory_limit;
+  const createdAt = value.created_at;
+  const updatedAt = value.updated_at;
+  if (typeof id !== "string" || typeof projectId !== "string" || typeof name !== "string") return null;
+  if (typeof gitUrl !== "string" || typeof branch !== "string" || typeof composePath !== "string") return null;
+  if (typeof createdAt !== "string" || typeof updatedAt !== "string") return null;
+  if (typeof memoryLimit !== "number" || !Number.isInteger(memoryLimit)) return null;
+  const view = {
+    id,
+    project_id: projectId,
+    name,
+    git_url: gitUrl,
+    branch,
+    compose_path: composePath,
+    memory_limit: memoryLimit,
+    created_at: createdAt,
+    updated_at: updatedAt,
+  };
+  const projectName = value.project_name;
+  if (typeof projectName === "string") {
+    return { ...view, project_name: projectName };
+  }
+  return view;
+}
+
+function composeLines(view) {
+  return [
+    view.id,
+    view.project_id,
+    view.name,
+    view.git_url,
+    view.branch,
+    view.compose_path,
+    String(view.memory_limit),
+    view.created_at,
+    view.updated_at,
+  ];
+}
+
+function composeListLine(view) {
+  const base = `${view.id} ${view.name}`;
+  return typeof view.project_name === "string" ? `${base} ${view.project_name}` : base;
+}
+
+function requireComposeId(io, key, json, rawId) {
+  const ids = Array.isArray(rawId) ? rawId : rawId === undefined ? [] : [rawId];
+  if (ids.length > 1) return { exit: fail(io, key, json, SENTENCE.refused) };
+  const id = appUuid(ids[0]);
+  if (id === null) return { exit: fail(io, key, json, SENTENCE.composeId) };
+  return { id };
+}
+
+async function composeList(args, io, key) {
+  const parsed = parseStrict(args, COMPOSE_LIST_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== "list") {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  if (parsed.values.id !== undefined) return fail(io, key, wantsJson(args), SENTENCE.refused);
+  const json = parsed.values.json === true;
+  const result = await call(io, key, { path: "/v1/compose", method: "GET" });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status, result.retryAfterSeconds));
+  const items = isRecord(result.body) && Array.isArray(result.body.compose) ? result.body.compose : null;
+  if (items === null) return fail(io, key, json, SENTENCE.failed);
+  const views = [];
+  for (const item of items) {
+    const row = composeFields(item);
+    if (row === null) return fail(io, key, json, SENTENCE.failed);
+    views.push(row);
+  }
+  const human = views.length === 0 ? "" : `${views.map((row) => composeListLine(row)).join("\n")}\n`;
+  return succeed(io, key, json, { compose: views }, human);
+}
+
+async function composeDeploy(args, io, key) {
+  const parsed = parseStrict(args, COMPOSE_ACTION_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== "deploy") {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const required = requireComposeId(io, key, json, parsed.values.id);
+  if (required.exit) return required.exit;
+  const result = await call(io, key, {
+    path: `/v1/compose/${encodeURIComponent(required.id)}/deploy`,
+    method: "POST",
+  });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 202) {
+    return fail(
+      io,
+      key,
+      json,
+      upgradeMessage(result.status, result.body) ?? composeUnavailableMessage(result.status, result.body) ?? sentenceFor(result.status, result.retryAfterSeconds),
+    );
+  }
+  const view = composeFields(isRecord(result.body) ? result.body.compose : null);
+  if (view === null) return fail(io, key, json, SENTENCE.failed);
+  const payload = { compose: view };
+  return succeed(io, key, json, payload, `${composeLines(view).join("\n")}\n`);
+}
+
+async function composeStartStop(args, io, key, action) {
+  const parsed = parseStrict(args, COMPOSE_ACTION_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== action) {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const required = requireComposeId(io, key, json, parsed.values.id);
+  if (required.exit) return required.exit;
+  const result = await call(io, key, {
+    path: `/v1/compose/${encodeURIComponent(required.id)}/${action}`,
+    method: "POST",
+  });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 200) {
+    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status, result.retryAfterSeconds));
+  }
+  const body = isRecord(result.body) ? result.body : null;
+  const view = body === null ? null : composeFields(body.compose);
+  const statusText = body?.status;
+  if (view === null || typeof statusText !== "string") return fail(io, key, json, SENTENCE.failed);
+  const payload = { compose: view, status: statusText };
+  const lines = [statusText, ...composeLines(view)];
+  return succeed(io, key, json, payload, `${lines.join("\n")}\n`);
+}
+
+export async function compose(args, io) {
+  const loaded = loadKey(io);
+  if (loaded.exit) return loaded.exit;
+  const words = composePositionals(args);
+  if (words === null || words.length !== 1) return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+  if (words[0] === "list") return composeList(args, io, loaded.key);
+  if (words[0] === "deploy") return composeDeploy(args, io, loaded.key);
+  if (words[0] === "start") return composeStartStop(args, io, loaded.key, "start");
+  if (words[0] === "stop") return composeStartStop(args, io, loaded.key, "stop");
+  return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+}

package/src/main.mjs

@@ -4,7 +4,7 @@ import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_BASE_URL } from "./client.mjs";
-import { accountExport, app, database, deploy, diagnose, domains, env, list, login, logout, logs, plans, preflight, restart, rollback, status, storage, usage, whoami } from "./commands.mjs";
+import { accountExport, app, compose, database, deploy, diagnose, domains, env, list, login, logout, logs, next, plans, preflight, restart, rollback, status, storage, usage, whoami } from "./commands.mjs";
 
 const PROMPT = "Paste your Astris API key: ";
 
@@ -48,6 +48,7 @@ const handlers = new Map([
   ["diagnose", diagnose],
   ["database", database],
   ["storage", storage],
+  ["compose", compose],
   ["env", env],
   ["domains", domains],
   ["restart", restart],
@@ -56,6 +57,7 @@ const handlers = new Map([
   ["usage", usage],
   ["plans", plans],
   ["whoami", whoami],
+  ["next", next],
   ["rollback", rollback],
   ["login", login],
   ["logout", logout],