@asteroidai/cli 0.0.0 → 1.8.197

package/src/http.ts

@@ -0,0 +1,115 @@
+import { type Auth, UNSET_API_KEY } from "./auth/credentials";
+import type { BuiltRequest } from "./request";
+
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly body: unknown,
+  ) {
+    super(message);
+  }
+}
+
+export interface ApiResponse {
+  status: number;
+  json?: unknown;
+  text?: string;
+  bytes?: Uint8Array;
+}
+
+export const VERSION = process.env.ASTEROID_CLI_VERSION ?? "dev";
+
+function problem(status: number, body: unknown, fallback: string): string {
+  if (body && typeof body === "object") {
+    const record = body as Record<string, unknown>;
+    for (const key of ["detail", "message", "error", "title"]) {
+      if (typeof record[key] === "string" && record[key])
+        return record[key] as string;
+    }
+  }
+  return fallback.trim() || `HTTP ${status}`;
+}
+
+export async function send(
+  apiUrl: string,
+  auth: Auth,
+  request: BuiltRequest,
+  binary: boolean,
+  fetchImpl: typeof fetch = fetch,
+): Promise<ApiResponse> {
+  const query = request.query.toString();
+  const url = `${apiUrl}${request.path}${query ? `?${query}` : ""}`;
+  const headers: Record<string, string> = {
+    ...auth.headers,
+    Accept: binary ? "*/*" : "application/json",
+    "User-Agent": `asteroid-cli/${VERSION}`,
+    "X-Request-Source": "asteroid-cli",
+  };
+  let body: BodyInit | undefined;
+  if (request.form) body = request.form;
+  else if (request.json !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(request.json);
+  }
+
+  let response = await fetchImpl(url, {
+    method: request.method,
+    headers,
+    body,
+    redirect: "manual",
+  });
+  let current = new URL(url);
+  let hopHeaders: Record<string, string> = { ...headers };
+  let method: string = request.method;
+  for (let hop = 0; hop < 5; hop++) {
+    const location = response.headers.get("location");
+    if (response.status < 300 || response.status >= 400 || !location) break;
+    const target = new URL(location, current);
+    if (target.origin !== current.origin) {
+      hopHeaders = { "User-Agent": headers["User-Agent"] };
+      if (headers["Content-Type"])
+        hopHeaders["Content-Type"] = headers["Content-Type"];
+    }
+    current = target;
+    const keepMethod = response.status === 307 || response.status === 308;
+    if (!keepMethod && method !== "HEAD") {
+      method = "GET";
+      body = undefined;
+      delete hopHeaders["Content-Type"];
+    }
+    response = await fetchImpl(target, {
+      method,
+      headers: hopHeaders,
+      body,
+      redirect: "manual",
+    });
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (!response.ok) {
+    const text = await response.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+    let message = problem(response.status, parsed, text.slice(0, 200));
+    const sentKey = "X-Api-Key" in hopHeaders;
+    if (sentKey && response.status === 401)
+      message = `ASTEROID_API_KEY was rejected: ${message}. Check the key. ${UNSET_API_KEY}`;
+    else if (sentKey && response.status === 403)
+      message = `${message} (sent with ASTEROID_API_KEY. ${UNSET_API_KEY})`;
+    throw new ApiError(response.status, message, parsed);
+  }
+  if (binary)
+    return {
+      status: response.status,
+      bytes: new Uint8Array(await response.arrayBuffer()),
+    };
+  if (response.status === 204) return { status: 204 };
+  if (contentType.includes("json"))
+    return { status: response.status, json: await response.json() };
+  return { status: response.status, text: await response.text() };
+}

package/src/main.ts

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+
+import { readEnv } from "./config";
+import { COMMANDS } from "./generated/commands";
+import { runCompletion } from "./program";
+import { BUILTINS } from "./reference";
+import { run } from "./run";
+import { clackUi } from "./ui";
+
+function openUrl(url: string) {
+  if (process.env.ASTEROID_NO_BROWSER || !/^https:\/\/[^\s"'<>^&|]+$/.test(url))
+    return;
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true })
+      .on("error", () => undefined)
+      .unref();
+  } catch {
+    return;
+  }
+}
+
+const argv = process.argv.slice(2);
+if (argv[0] === "complete") {
+  await runCompletion(argv, { commands: COMMANDS, builtins: BUILTINS });
+  process.exit(0);
+}
+
+const code = await run(argv, {
+  env: readEnv(),
+  cwd: process.cwd(),
+  fetch,
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+  writeBytes: (bytes) => process.stdout.write(bytes),
+  ui: process.stdin.isTTY && process.stderr.isTTY ? clackUi : undefined,
+  stdoutIsTTY: process.stdout.isTTY === true,
+  styled:
+    process.stdout.isTTY === true &&
+    !process.env.NO_COLOR &&
+    process.env.TERM !== "dumb",
+  openUrl,
+});
+process.exitCode = code;

package/src/output.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { clean, render } from "./output";
+
+describe("clean", () => {
+  it("strips escape sequences and control characters, keeps newlines and tabs", () => {
+    const hostile =
+      "a\u001b[31mred\u001b[0m\u001b]0;title\u0007b\rc\u0008d\te\nf\u009bg";
+    expect(clean(hostile)).toBe("aredbcd\te\nfg");
+  });
+});
+
+describe("render", () => {
+  it("cleans server text in tables and records", () => {
+    const plain = render({ items: [{ id: "1", name: "x\u001b[2Jy" }] });
+    expect(plain).toContain("xy");
+    expect(plain).not.toContain("\u001b");
+    expect(render({ note: "a\u0007b" })).toContain("ab");
+  });
+
+  it("draws a bordered table only when styled", () => {
+    const rows = [{ id: "1", name: "Ada" }];
+    expect(render(rows)).not.toContain("┌");
+    expect(render(rows, { styled: true })).toContain("┌");
+  });
+});

package/src/output.ts

@@ -0,0 +1,153 @@
+import Table from "cli-table3";
+import { styleText } from "node:util";
+
+const PREFERRED = [
+  "id",
+  "name",
+  "title",
+  "workflowName",
+  "status",
+  "outcome",
+  "version",
+  "createdAt",
+  "updatedAt",
+];
+const HIDDEN = /^agent[A-Z]|Url$/;
+const MAX_COLUMNS = 6;
+const MAX_CELL = 60;
+const CONTROL =
+  /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[@-_]?|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+
+type Row = Record<string, unknown>;
+
+export interface RenderOptions {
+  styled?: boolean;
+}
+
+export function clean(text: string): string {
+  return text.replace(CONTROL, "");
+}
+
+function isObject(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isScalar(value: unknown): boolean {
+  return (
+    value === null || ["string", "number", "boolean"].includes(typeof value)
+  );
+}
+
+function indent(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+function text(value: unknown): string {
+  return clean(isScalar(value) ? String(value) : JSON.stringify(value));
+}
+
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const line = text(value).replace(/\s+/g, " ");
+  return line.length > MAX_CELL ? `${line.slice(0, MAX_CELL - 1)}…` : line;
+}
+
+function columns(rows: Row[]): string[] {
+  const scalarKeys: string[] = [];
+  for (const row of rows) {
+    for (const [key, value] of Object.entries(row)) {
+      if (isScalar(value) && !HIDDEN.test(key) && !scalarKeys.includes(key))
+        scalarKeys.push(key);
+    }
+  }
+  const ordered = [
+    ...PREFERRED.filter((key) => scalarKeys.includes(key)),
+    ...scalarKeys.filter((key) => !PREFERRED.includes(key)),
+  ];
+  return ordered.slice(0, MAX_COLUMNS);
+}
+
+function style(
+  format: Parameters<typeof styleText>[0],
+  value: string,
+  options: RenderOptions,
+) {
+  return options.styled
+    ? styleText(format, value, { validateStream: false })
+    : value;
+}
+
+export function table(rows: Row[], options: RenderOptions = {}): string {
+  if (rows.length === 0) return "No results.";
+  const keys = columns(rows);
+  if (keys.length === 0) return rows.map((row) => text(row)).join("\n");
+  const cells = rows.map((row) => keys.map((key) => cell(row[key])));
+  if (options.styled) {
+    const grid = new Table({
+      head: keys.map((key) => style("bold", key, options)),
+      style: { head: [], border: [] },
+    });
+    grid.push(...cells);
+    return grid.toString();
+  }
+  const widths = keys.map((key, i) =>
+    Math.max(key.length, ...cells.map((r) => r[i].length)),
+  );
+  const line = (values: string[]) =>
+    values
+      .map((v, i) => v.padEnd(widths[i]))
+      .join("  ")
+      .trimEnd();
+  return [line(keys.map((k) => k.toUpperCase())), ...cells.map(line)].join(
+    "\n",
+  );
+}
+
+function summary(value: unknown): string {
+  if (Array.isArray(value))
+    return `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  if (value && typeof value === "object") return cell(value);
+  return text(value);
+}
+
+function record(value: Row, options: RenderOptions): string {
+  const width = Math.max(...Object.keys(value).map((key) => key.length));
+  const label = (key: string) => style("bold", key.padEnd(width), options);
+  return Object.entries(value)
+    .map(([key, v]) => {
+      if (Array.isArray(v) && v.length > 0 && v.every(isObject)) {
+        return `${style("bold", key, options)}:\n${indent(table(v as Row[], options))}`;
+      }
+      if (Array.isArray(v) && v.length > 0 && v.every(isScalar)) {
+        return `${label(key)}  ${v.map(text).join(`\n${" ".repeat(width + 2)}`)}`;
+      }
+      return `${label(key)}  ${isScalar(v) ? text(v) : summary(v)}`;
+    })
+    .join("\n");
+}
+
+export function render(value: unknown, options: RenderOptions = {}): string {
+  if (value === undefined) return "";
+  if (Array.isArray(value)) {
+    return value.every(isObject)
+      ? table(value as Row[], options)
+      : value.map(text).join("\n");
+  }
+  if (isObject(value)) {
+    const row = value as Row;
+    if (Array.isArray(row.items)) {
+      const rest = Object.entries(row).filter(
+        ([k, v]) => k !== "items" && isScalar(v),
+      );
+      const footer = rest.length
+        ? `\n\n${style("dim", rest.map(([k, v]) => `${k}: ${text(v)}`).join("  "), options)}`
+        : "";
+      return `${table(row.items as Row[], options)}${footer}`;
+    }
+    return record(row, options);
+  }
+  return text(value);
+}

package/src/program.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import { COMMANDS } from "./generated/commands";
+import { type Invocation, parseInvocation } from "./program";
+import { BUILTINS } from "./reference";
+
+const parse = (argv: string[]) =>
+  parseInvocation(argv, { commands: COMMANDS, builtins: BUILTINS });
+
+function command(invocation: Invocation) {
+  if (invocation.kind !== "command")
+    throw new Error(`expected a command, got ${invocation.kind}`);
+  return invocation;
+}
+
+describe("parseInvocation", () => {
+  it("collects repeated flags, globals anywhere, and positionals", async () => {
+    const got = command(
+      await parse([
+        "--json",
+        "execution",
+        "list",
+        "--status",
+        "failed",
+        "--status",
+        "completed",
+        "--org",
+        "acme",
+      ]),
+    );
+    expect(got.command.tool).toBe("executions_list");
+    expect(got.parsed.flags.get("status")).toEqual(["failed", "completed"]);
+    expect(got.parsed.json).toBe(true);
+    expect(got.parsed.org).toBe("acme");
+  });
+
+  it("keeps dotted body flags for the request builder", async () => {
+    const got = command(
+      await parse([
+        "workflow",
+        "execute",
+        "w-1",
+        "--execution-options.variant-key",
+        "canary",
+      ]),
+    );
+    expect(got.parsed.positionals).toEqual(["w-1"]);
+    expect(got.parsed.flags.get("execution-options.variant-key")).toEqual([
+      "canary",
+    ]);
+  });
+
+  it("rejects a dotted flag no body field owns", async () => {
+    await expect(
+      parse(["workflow", "list", "--nope.deep", "1"]),
+    ).rejects.toThrow(/unknown flag: --nope.deep/);
+  });
+
+  it("reads --no-<flag> as false", async () => {
+    const got = command(
+      await parse(["schedule", "update", "w-1", "s-1", "--no-enabled"]),
+    );
+    expect(got.parsed.flags.get("enabled")).toEqual(["false"]);
+  });
+
+  it("routes account commands as builtins and checks their arguments", async () => {
+    const use = await parse(["use", "acme"]);
+    expect(use).toMatchObject({ kind: "builtin", name: "use" });
+    expect(await parse(["use", "a", "b"])).toMatchObject({
+      kind: "exit",
+      code: 2,
+    });
+    expect(await parse(["logout", "--typo", "x"])).toMatchObject({
+      kind: "exit",
+      code: 2,
+    });
+  });
+
+  it("shows group and command help with exit 0", async () => {
+    const group = await parse(["workflow", "version"]);
+    expect(group).toMatchObject({ kind: "exit", code: 0 });
+    expect(group.kind === "exit" && group.stdout + group.stderr).toContain(
+      "publish",
+    );
+    const leaf = await parse(["workflow", "get", "--help"]);
+    expect(leaf.kind === "exit" && leaf.stdout).toContain("<workflow-id>");
+  });
+
+  it("fills a defaulted first argument when it is left out", async () => {
+    const got = command(
+      await parseInvocation(["workflow", "tag", "list"], {
+        commands: COMMANDS,
+        defaultArg: (_, arg) =>
+          arg.name === "workflowId" ? "chat-wf" : undefined,
+      }),
+    );
+    expect(got.parsed.positionals).toEqual(["chat-wf"]);
+  });
+});

package/src/program.ts

@@ -0,0 +1,256 @@
+import { Command, CommanderError } from "commander";
+
+import { type Parsed, UsageError } from "./args";
+import { type BuiltinCommand, GLOBAL_FLAGS } from "./reference";
+import type { CliCommand, Option } from "./types";
+
+export type Invocation =
+  | { kind: "command"; command: CliCommand; parsed: Parsed }
+  | { kind: "builtin"; name: string; parsed: Parsed }
+  | { kind: "exit"; code: number; stdout: string; stderr: string };
+
+export interface ProgramOptions {
+  commands: readonly CliCommand[];
+  builtins?: readonly BuiltinCommand[];
+  version?: string;
+  description?: string;
+  defaultArg?: (command: CliCommand, arg: Option) => string | undefined;
+  defaultArgNote?: string;
+}
+
+const DOTTED = /^--([a-z0-9-]+\.[a-z0-9.-]+)(?:=(.*))?$/;
+
+function collect(value: string, previous: string[] | undefined): string[] {
+  return [...(previous ?? []), value];
+}
+
+function optionText(option: Option): string {
+  const text = option.description?.replace(/\s+/g, " ").trim() ?? "";
+  const parts = [text && !/[.!?]$/.test(text) ? `${text}.` : text];
+  if (option.enum) parts.push(`One of: ${option.enum.join(", ")}.`);
+  if (option.type.endsWith("[]")) parts.push("Repeatable.");
+  if (option.required) parts.push("Required.");
+  return parts.filter(Boolean).join(" ");
+}
+
+function splitDotted(argv: string[]): {
+  argv: string[];
+  dotted: Map<string, string[]>;
+} {
+  const rest: string[] = [];
+  const dotted = new Map<string, string[]>();
+  for (let i = 0; i < argv.length; i++) {
+    const match = DOTTED.exec(argv[i]);
+    if (!match) {
+      rest.push(argv[i]);
+      continue;
+    }
+    const value = match[2] ?? argv[++i];
+    if (value === undefined)
+      throw new UsageError(`--${match[1]} needs a value`);
+    dotted.set(match[1], [...(dotted.get(match[1]) ?? []), value]);
+  }
+  return { argv: rest, dotted };
+}
+
+function group(
+  parent: Command,
+  name: string,
+  groups: Map<string, Command>,
+  path: string,
+) {
+  const existing = groups.get(path);
+  if (existing) return existing;
+  const created = parent
+    .command(name)
+    .description(`${name} commands`)
+    .helpCommand(false);
+  groups.set(path, created);
+  return created;
+}
+
+function leafOptions(leaf: Command, command: CliCommand) {
+  for (const option of [...command.query, ...(command.body?.fields ?? [])]) {
+    if (option.type === "boolean") {
+      leaf.option(`--${option.flag}`, optionText(option));
+      leaf.option(`--no-${option.flag}`, `Set ${option.flag} to false.`);
+      continue;
+    }
+    const placeholder = option.enum
+      ? option.enum.join("|")
+      : option.type.replace("[]", "");
+    leaf.option(
+      `--${option.flag} <${placeholder}>`,
+      optionText(option),
+      collect,
+    );
+  }
+  for (const file of command.body?.files ?? []) {
+    leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
+  }
+}
+
+function toParsed(
+  leaf: Command,
+  positionals: string[],
+  dotted: Map<string, string[]>,
+): Parsed {
+  const globals = leaf.optsWithGlobals<Record<string, unknown>>();
+  const own = leaf.opts<Record<string, unknown>>();
+  const flags = new Map(dotted);
+  for (const option of leaf.options) {
+    const flag = option.long?.replace(/^--(no-)?/, "");
+    const value = own[option.attributeName()];
+    if (!flag || value === undefined || flags.has(flag)) continue;
+    flags.set(flag, Array.isArray(value) ? value.map(String) : [String(value)]);
+  }
+  return {
+    positionals,
+    flags,
+    json: globals.json === true,
+    org: globals.org as string | undefined,
+    body: globals.body as string | undefined,
+    output: globals.output as string | undefined,
+  };
+}
+
+export function defineCommands(
+  root: Command,
+  options: ProgramOptions,
+  dotted: Map<string, string[]> = new Map(),
+  onInvocation: (invocation: Invocation) => void = () => undefined,
+): Command {
+  if (options.description) root.description(options.description);
+  if (options.version) root.version(options.version, "-v, --version");
+  for (const [flags, text] of GLOBAL_FLAGS) {
+    if (!flags.startsWith("-h")) root.option(flags, text);
+  }
+
+  for (const builtin of options.builtins ?? []) {
+    const leaf = root.command(builtin.command).description(builtin.description);
+    if (builtin.arg) leaf.argument(`[${builtin.arg}]`);
+    leaf.action((...args: unknown[]) => {
+      const cmd = args.at(-1) as Command;
+      onInvocation({
+        kind: "builtin",
+        name: builtin.command,
+        parsed: toParsed(cmd, cmd.args, new Map()),
+      });
+    });
+  }
+
+  const reserved = new Set((options.builtins ?? []).map((b) => b.command));
+  const groups = new Map<string, Command>();
+  for (const command of options.commands) {
+    if (reserved.has(command.command)) continue;
+    const words = command.command.split(" ");
+    let parent = root;
+    for (let i = 0; i < words.length - 1; i++) {
+      parent = group(parent, words[i], groups, words.slice(0, i + 1).join(" "));
+    }
+    const leaf = parent
+      .command(words.at(-1)!)
+      .description(command.description)
+      .summary(command.title);
+    const defaults = command.args.map((arg) =>
+      options.defaultArg?.(command, arg),
+    );
+    command.args.forEach((arg, i) => {
+      leaf.argument(
+        defaults[i] === undefined ? `<${arg.flag}>` : `[${arg.flag}]`,
+        arg.description ?? "",
+      );
+    });
+    if (
+      defaults.some((value) => value !== undefined) &&
+      options.defaultArgNote
+    ) {
+      leaf.addHelpText("after", `\n${options.defaultArgNote}`);
+    }
+    leafOptions(leaf, command);
+    leaf.action((...args: unknown[]) => {
+      const cmd = args.at(-1) as Command;
+      let positionals = cmd.args;
+      if (
+        positionals.length === command.args.length - 1 &&
+        defaults[0] !== undefined
+      ) {
+        positionals = [defaults[0], ...positionals];
+      }
+      if (positionals.length !== command.args.length) {
+        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        throw new UsageError(
+          `expected ${expected}, got ${cmd.args.length} argument(s)`,
+        );
+      }
+      const unknownDotted = [...dotted.keys()].filter(
+        (flag) =>
+          !(command.body?.fields ?? []).some((f) =>
+            flag.startsWith(`${f.flag}.`),
+          ),
+      );
+      if (unknownDotted.length > 0) {
+        throw new UsageError(
+          `unknown flag: ${unknownDotted.map((f) => `--${f}`).join(", ")}`,
+        );
+      }
+      onInvocation({
+        kind: "command",
+        command,
+        parsed: toParsed(cmd, positionals, dotted),
+      });
+    });
+  }
+
+  return root;
+}
+
+export async function parseInvocation(
+  argv: string[],
+  options: ProgramOptions,
+): Promise<Invocation> {
+  let stdout = "";
+  let stderr = "";
+  let result: Invocation | undefined;
+
+  const { argv: rest, dotted } = splitDotted(argv);
+  const root = new Command("asteroid")
+    .exitOverride()
+    .helpCommand(false)
+    .configureOutput({
+      writeOut: (text) => (stdout += text),
+      writeErr: (text) => (stderr += text),
+    });
+  defineCommands(root, options, dotted, (invocation) => {
+    result = invocation;
+  });
+
+  try {
+    await root.parseAsync(rest, { from: "user" });
+  } catch (error) {
+    if (!(error instanceof CommanderError)) throw error;
+    if (error.code === "commander.help") {
+      return { kind: "exit", code: 0, stdout: stdout + stderr, stderr: "" };
+    }
+    const shown = ["commander.helpDisplayed", "commander.version"];
+    return {
+      kind: "exit",
+      code: shown.includes(error.code) ? 0 : 2,
+      stdout,
+      stderr,
+    };
+  }
+  if (result) return result;
+  root.outputHelp();
+  return { kind: "exit", code: 0, stdout, stderr };
+}
+
+export async function runCompletion(argv: string[], options: ProgramOptions) {
+  const { default: tab } = await import("@bomb.sh/tab/commander");
+  const root = defineCommands(new Command("asteroid").helpCommand(false), {
+    ...options,
+    builtins: options.builtins?.filter((b) => b.command !== "complete"),
+  });
+  tab(root);
+  await root.parseAsync(argv, { from: "user" });
+}