@asteroidai/cli 0.0.0 → 1.8.197

package/src/reference.ts

@@ -0,0 +1,170 @@
+import type { CliCommand, Option } from "./types";
+
+export interface BuiltinCommand {
+  command: string;
+  usage: string;
+  description: string;
+  args: number;
+  arg?: string;
+}
+
+export const BUILTINS: BuiltinCommand[] = [
+  {
+    command: "login",
+    usage: "asteroid login",
+    description:
+      "Sign in with your browser. Stores a refresh token in the OS keychain, or in a private file in the config directory when no keychain is available.",
+    args: 0,
+  },
+  {
+    command: "logout",
+    usage: "asteroid logout",
+    description: "Forget the stored sign-in and cached tokens.",
+    args: 0,
+  },
+  {
+    command: "orgs",
+    usage: "asteroid orgs",
+    description:
+      "List the organizations you can act in. The active one is marked.",
+    args: 0,
+  },
+  {
+    command: "use",
+    usage: "asteroid use [org]",
+    arg: "org",
+    description:
+      "Make an organization, by id or name, the default for later commands. Without one, pick from a list.",
+    args: 1,
+  },
+  {
+    command: "complete",
+    usage: "asteroid complete <zsh|bash|fish|powershell>",
+    arg: "shell",
+    description:
+      "Print a shell completion script. For zsh: `asteroid complete zsh > ~/.zfunc/_asteroid`.",
+    args: 1,
+  },
+  {
+    command: "whoami",
+    usage: "asteroid whoami",
+    description:
+      "Show who you act as, in which organization, and how long the token lasts.",
+    args: 0,
+  },
+];
+
+const BUILTIN_COMMANDS = new Set(BUILTINS.map((b) => b.command));
+
+function generated(commands: CliCommand[]): CliCommand[] {
+  return commands.filter((c) => !BUILTIN_COMMANDS.has(c.command));
+}
+
+export const GLOBAL_FLAGS: [string, string][] = [
+  ["--json", "Print the response as JSON."],
+  [
+    "--org <id|name>",
+    "Act in this organization for one command. Also ASTEROID_ORG.",
+  ],
+  [
+    "--body <json|@file|->",
+    "Request body as JSON, a file, or stdin. Flags override its fields.",
+  ],
+  ["--output <file>", "Write a downloaded file here, not to stdout."],
+  ["-h, --help", "Show help."],
+];
+
+export function usage(command: CliCommand): string {
+  const args = command.args.map((arg) => `<${arg.flag}>`).join(" ");
+  return `asteroid ${command.command}${args ? ` ${args}` : ""} [flags]`;
+}
+
+function flagLine(option: Option, prefix = ""): string {
+  const value =
+    option.type === "boolean"
+      ? ""
+      : option.enum
+        ? ` <${option.enum.join("|")}>`
+        : ` <${option.type}>`;
+  const notes = [
+    option.required ? "required" : "",
+    option.type.endsWith("[]") ? "repeatable" : "",
+  ].filter(Boolean);
+  const description = [
+    option.description?.replace(/\s+/g, " ").trim() ?? "",
+    notes.length ? `(${notes.join(", ")})` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const name =
+    option.type === "boolean"
+      ? `[no-]${prefix}${option.flag}`
+      : `${prefix}${option.flag}`;
+  return `--${name}${value}${description ? `  ${description}` : ""}`;
+}
+
+export function flagLines(command: CliCommand): string[] {
+  const lines = command.query.map((option) => flagLine(option));
+  for (const field of command.body?.fields ?? []) lines.push(flagLine(field));
+  for (const file of command.body?.files ?? []) {
+    lines.push(`--${file} <path>  File to upload (repeatable)`);
+  }
+  return lines;
+}
+
+function mdx(text: string): string {
+  return text
+    .split("`")
+    .map((part, i) =>
+      i % 2 === 1
+        ? part
+        : part
+            .replace(/</g, "&lt;")
+            .replace(/\{/g, "&#123;")
+            .replace(/\}/g, "&#125;"),
+    )
+    .join("`");
+}
+
+export function renderReference(commands: CliCommand[]): string {
+  const lines = [
+    "---",
+    'title: "CLI reference"',
+    'description: "Every asteroid command, its arguments and its flags"',
+    "---",
+    "",
+    "{/* Generated by packages/asteroid-cli from the cli surface of the External API. Do not edit by hand. */}",
+    "",
+    "Sign in with `asteroid login`, or set `ASTEROID_API_KEY` for CI and agents.",
+    "Commands that return data print compact text. Add `--json` to get the response as JSON.",
+    "The text output may change between releases. Scripts should read `--json`.",
+    "Downloads write raw bytes. `login`, `logout` and `use` only report status on stderr.",
+    "Exit codes: 0 ok, 1 API error, 2 usage error.",
+    "",
+    "## Global flags",
+    "",
+  ];
+  for (const [flag, text] of GLOBAL_FLAGS)
+    lines.push(`- \`${flag}\`: ${mdx(text)}`);
+  lines.push("", "## Account", "");
+  for (const builtin of BUILTINS) {
+    lines.push(`### \`${builtin.usage}\``, "", mdx(builtin.description), "");
+  }
+  lines.push("## Commands", "");
+  for (const command of generated(commands)) {
+    lines.push(`### \`${usage(command)}\``, "", mdx(command.description), "");
+    for (const arg of command.args) {
+      lines.push(
+        `- \`<${arg.flag}>\`${arg.description ? `: ${mdx(arg.description)}` : ""}`,
+      );
+    }
+    for (const flag of flagLines(command)) {
+      const [name, ...rest] = flag.split("  ");
+      lines.push(
+        `- \`${name}\`${rest.length ? `: ${mdx(rest.join("  "))}` : ""}`,
+      );
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/request.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+
+import { matchCommand, UsageError } from "./args";
+import { COMMANDS } from "./generated/commands";
+import { parseInvocation } from "./program";
+import { buildRequest, type InputReader } from "./request";
+
+async function build(argv: string[], io?: InputReader) {
+  const invocation = await parseInvocation(argv, { commands: COMMANDS });
+  if (invocation.kind !== "command") {
+    throw new UsageError(
+      invocation.kind === "exit" ? invocation.stderr : "no command",
+    );
+  }
+  return buildRequest(invocation.command, invocation.parsed, { io });
+}
+
+describe("matchCommand", () => {
+  it("takes the longest command and leaves ids as arguments", () => {
+    const { command } = matchCommand(
+      ["workflow", "version", "get", "w1", "v1"],
+      COMMANDS,
+    );
+    expect(command?.tool).toBe("workflow_version_get");
+  });
+
+  it("returns a group prefix when no command matches", () => {
+    const { command, prefix } = matchCommand(["workflow", "version"], COMMANDS);
+    expect(command).toBeUndefined();
+    expect(prefix).toEqual(["workflow", "version"]);
+  });
+});
+
+describe("buildRequest", async () => {
+  it("fills path arguments in order", async () => {
+    const request = await build(["workflow", "version", "get", "w-1", "v-2"]);
+    expect(request.method).toBe("GET");
+    expect(request.path).toBe("/agents/v2/workflows/w-1/versions/v-2");
+  });
+
+  it("repeats array query flags and checks enums", async () => {
+    const request = await build([
+      "execution",
+      "list",
+      "--status",
+      "failed",
+      "--status=completed",
+      "--page-size",
+      "5",
+    ]);
+    expect(request.query.getAll("status")).toEqual(["failed", "completed"]);
+    expect(request.query.get("pageSize")).toBe("5");
+    await expect(
+      build(["execution", "list", "--status", "nope"]),
+    ).rejects.toThrow(UsageError);
+  });
+
+  it("rejects a non-integer for an integer flag", async () => {
+    await expect(
+      build(["execution", "list", "--page-size", "five"]),
+    ).rejects.toThrow(/integer/);
+  });
+
+  it("nests dotted flags into the body", async () => {
+    const request = await build([
+      "workflow",
+      "execute",
+      "w-1",
+      "--execution-options.variant-key",
+      "canary",
+      "--inputs",
+      '{"name":"Ada"}',
+    ]);
+    expect(request.json).toMatchObject({
+      executionOptions: { variantKey: "canary" },
+      inputs: { name: "Ada" },
+    });
+  });
+
+  it("lets flags override --body fields", async () => {
+    const request = await build([
+      "schema",
+      "validate",
+      "--body",
+      '{"schema":{"type":"string"}}',
+      "--schema",
+      '{"type":"object"}',
+    ]);
+    expect(request.json).toEqual({ schema: { type: "object" } });
+  });
+
+  it("fails on unknown flags and missing arguments", async () => {
+    await expect(build(["workflow", "list", "--nope", "1"])).rejects.toThrow(
+      /unknown option '--nope'/,
+    );
+    await expect(build(["workflow", "get"])).rejects.toThrow(
+      /missing required argument 'workflow-id'/,
+    );
+  });
+
+  it("requires required body fields", async () => {
+    await expect(build(["schema", "validate"])).rejects.toThrow(
+      /--schema is required/,
+    );
+  });
+
+  it("does not take a following flag as a value", async () => {
+    await expect(
+      build(["workflow", "rename", "w1", "--name", "--json"]),
+    ).rejects.toThrow(/'--name <string>' argument missing/);
+  });
+
+  it("rejects a --body that is not an object", async () => {
+    await expect(
+      build(["schema", "validate", "--body", "null"]),
+    ).rejects.toThrow(/--body must be a JSON object/);
+  });
+
+  it("requires files on an upload and refuses --body there", async () => {
+    await expect(build(["temp-file", "upload"])).rejects.toThrow(
+      /--files is required/,
+    );
+    await expect(
+      build(["temp-file", "upload", "--body", "{}"]),
+    ).rejects.toThrow(/use the file flags/);
+  });
+
+  it("reads @file and stdin through the reader it is given", async () => {
+    const io: InputReader = {
+      text: async (path) =>
+        path === 0 ? '{"schema":{"type":"string"}}' : '{"type":"object"}',
+      bytes: async () => new Uint8Array(),
+    };
+    const fromFile = await build(
+      ["schema", "validate", "--schema", "@/workspace/s.json"],
+      io,
+    );
+    expect(fromFile.json).toEqual({ schema: { type: "object" } });
+    const fromStdin = await build(["schema", "validate", "--body", "-"], io);
+    expect(fromStdin.json).toEqual({ schema: { type: "string" } });
+  });
+
+  it("takes the organization from the credential, never from flags or --body", async () => {
+    await expect(
+      build(["tag", "list", "--organization-id", "other"]),
+    ).rejects.toThrow(/unknown option '--organization-id'/);
+    const invocation = await parseInvocation(
+      [
+        "workflow",
+        "create",
+        "--name",
+        "W",
+        "--body",
+        '{"organizationId":"other"}',
+      ],
+      { commands: COMMANDS },
+    );
+    if (invocation.kind !== "command") throw new Error("expected a command");
+    const request = await buildRequest(invocation.command, invocation.parsed, {
+      organizationId: "mine",
+    });
+    expect(request.json).toMatchObject({ organizationId: "mine", name: "W" });
+  });
+});

package/src/request.ts

@@ -0,0 +1,252 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+import { type Parsed, UsageError } from "./args";
+import type { CliCommand, Option } from "./types";
+
+export interface BuiltRequest {
+  method: CliCommand["method"];
+  path: string;
+  query: URLSearchParams;
+  json?: unknown;
+  form?: FormData;
+}
+
+function camel(segment: string): string {
+  return segment.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+function scalar(option: Option, raw: string): unknown {
+  const type = option.type.replace("[]", "");
+  if (option.enum && !option.enum.includes(raw)) {
+    throw new UsageError(
+      `--${option.flag} must be one of ${option.enum.join(", ")}`,
+    );
+  }
+  if (type === "integer" || type === "number") {
+    const value = Number(raw);
+    if (
+      raw.trim() === "" ||
+      Number.isNaN(value) ||
+      (type === "integer" && !Number.isInteger(value))
+    ) {
+      throw new UsageError(
+        `--${option.flag} must be ${type === "integer" ? "an integer" : "a number"}`,
+      );
+    }
+    return value;
+  }
+  if (type === "boolean") {
+    if (raw !== "true" && raw !== "false") {
+      throw new UsageError(`--${option.flag} must be true or false`);
+    }
+    return raw === "true";
+  }
+  if (type === "json") return parseJson(raw, `--${option.flag}`);
+  return raw;
+}
+
+function value(option: Option, raws: string[]): unknown {
+  if (option.type.endsWith("[]")) return raws.map((raw) => scalar(option, raw));
+  return scalar(option, raws.at(-1)!);
+}
+
+export interface InputReader {
+  text(path: string | 0): Promise<string>;
+  bytes(path: string): Promise<Uint8Array<ArrayBuffer>>;
+}
+
+export const nodeReader: InputReader = {
+  text: async (path) => readFileSync(path, "utf8"),
+  bytes: async (path) => new Uint8Array(readFileSync(path)),
+};
+
+async function readInput(raw: string, io: InputReader): Promise<string> {
+  if (raw === "-") return io.text(0);
+  if (raw.startsWith("@")) return io.text(raw.slice(1));
+  return raw;
+}
+
+async function resolveInputs(
+  command: CliCommand,
+  parsed: Parsed,
+  io: InputReader,
+): Promise<Parsed> {
+  const jsonFlags = [...command.query, ...(command.body?.fields ?? [])]
+    .filter((option) => option.type === "json")
+    .map((option) => option.flag);
+  const flags = new Map(parsed.flags);
+  for (const flag of jsonFlags) {
+    const raws = flags.get(flag);
+    if (raws)
+      flags.set(flag, await Promise.all(raws.map((raw) => readInput(raw, io))));
+  }
+  const body =
+    parsed.body === undefined ? undefined : await readInput(parsed.body, io);
+  return { ...parsed, flags, body };
+}
+
+function parseJson(raw: string, label: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new UsageError(`${label} is not valid JSON`);
+  }
+}
+
+function loose(raw: string): unknown {
+  if (/^(true|false|null)$/.test(raw) || /^[[{]/.test(raw.trim())) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  return raw;
+}
+
+function setPath(
+  target: Record<string, unknown>,
+  path: string[],
+  value: unknown,
+) {
+  let node = target;
+  for (const key of path.slice(0, -1)) {
+    const next = node[key];
+    if (typeof next !== "object" || next === null || Array.isArray(next))
+      node[key] = {};
+    node = node[key] as Record<string, unknown>;
+  }
+  node[path.at(-1)!] = value;
+}
+
+export interface RequestContext {
+  io?: InputReader;
+  organizationId?: string;
+}
+
+export async function buildRequest(
+  command: CliCommand,
+  input: Parsed,
+  context: RequestContext = {},
+): Promise<BuiltRequest> {
+  const io = context.io ?? nodeReader;
+  const parsed = await resolveInputs(command, input, io);
+  if (parsed.positionals.length !== command.args.length) {
+    const expected =
+      command.args.map((a) => `<${a.flag}>`).join(" ") || "no arguments";
+    throw new UsageError(
+      `expected ${expected}, got ${parsed.positionals.length} argument(s)`,
+    );
+  }
+  let path = command.path;
+  command.args.forEach((arg, i) => {
+    path = path.replace(
+      `{${arg.name}}`,
+      encodeURIComponent(parsed.positionals[i]),
+    );
+  });
+
+  const flags = new Map(parsed.flags);
+  const query = new URLSearchParams();
+  for (const option of command.query) {
+    const raws = flags.get(option.flag);
+    flags.delete(option.flag);
+    if (!raws) {
+      if (option.required) throw new UsageError(`--${option.flag} is required`);
+      continue;
+    }
+    const parsedValue = value(option, raws);
+    const values = Array.isArray(parsedValue) ? parsedValue : [parsedValue];
+    if (option.explode === false)
+      query.append(option.name, values.map(String).join(","));
+    else for (const v of values) query.append(option.name, String(v));
+  }
+
+  const built: BuiltRequest = { method: command.method, path, query };
+  const body = command.body;
+  if (!body) {
+    if (parsed.body) throw new UsageError(`${command.command} takes no body`);
+    rejectUnknown(flags);
+    return built;
+  }
+
+  if (body.contentType === "multipart/form-data") {
+    if (parsed.body) {
+      throw new UsageError(
+        `${command.command} uploads files; use the file flags, not --body`,
+      );
+    }
+    const form = new FormData();
+    for (const file of body.files) {
+      const paths = flags.get(file) ?? [];
+      if (body.required && paths.length === 0) {
+        throw new UsageError(`--${file} is required`);
+      }
+      for (const filePath of paths) {
+        form.append(
+          file,
+          new Blob([await io.bytes(filePath)]),
+          basename(filePath),
+        );
+      }
+      flags.delete(file);
+    }
+    for (const field of body.fields) {
+      const raws = flags.get(field.flag);
+      flags.delete(field.flag);
+      if (raws) for (const raw of raws) form.append(field.name, raw);
+    }
+    rejectUnknown(flags);
+    built.form = form;
+    return built;
+  }
+
+  const base = parsed.body ? parseJson(parsed.body, "--body") : {};
+  if (typeof base !== "object" || base === null || Array.isArray(base)) {
+    throw new UsageError("--body must be a JSON object");
+  }
+  const json = base as Record<string, unknown>;
+  for (const field of body.fields) {
+    const raws = flags.get(field.flag);
+    if (!raws) continue;
+    flags.delete(field.flag);
+    json[field.name] = value(field, raws);
+  }
+  for (const [flag, raws] of [...flags]) {
+    const [head, ...rest] = flag.split(".");
+    const field = body.fields.find((f) => f.flag === head);
+    if (!field || rest.length === 0) continue;
+    flags.delete(flag);
+    const current = json[field.name];
+    json[field.name] =
+      typeof current === "object" && current !== null ? current : {};
+    setPath(json, [field.name, ...rest.map(camel)], loose(raws.at(-1)!));
+  }
+  rejectUnknown(flags);
+  delete json.organizationId;
+  if (body.credentialOrganization) {
+    if (!context.organizationId) {
+      throw new UsageError(
+        "could not tell which organization this credential acts in",
+      );
+    }
+    json.organizationId = context.organizationId;
+  }
+  for (const field of body.fields) {
+    if (field.required && json[field.name] === undefined) {
+      throw new UsageError(`--${field.flag} is required`);
+    }
+  }
+  if (body.required || Object.keys(json).length > 0) built.json = json;
+  return built;
+}
+
+function rejectUnknown(flags: Map<string, string[]>) {
+  const unknown = [...flags.keys()];
+  if (unknown.length > 0) {
+    throw new UsageError(
+      `unknown flag${unknown.length > 1 ? "s" : ""}: ${unknown.map((f) => `--${f}`).join(", ")}`,
+    );
+  }
+}