@astris-labs/cli 0.1.2 → 0.1.3

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. 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.3",
   "description": "The Astris CLI, a command-line client of the Astris API.",
   "repository": {
     "type": "git",

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,6 +58,7 @@ 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],
 ]);
 
@@ -1826,3 +1828,196 @@ 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));
+  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));
+  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) ?? sentenceFor(result.status));
+  }
+  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));
+  }
+  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],