@asteroidai/cli 1.9.27 → 1.9.28

package/src/program.ts

@@ -1,293 +0,0 @@
-import { Command, CommanderError, Option as Flag } 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;
-  helpNote?: (command: CliCommand) => string | undefined;
-}
-
-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,
-    );
-    if (option.negatable)
-      leaf.option(`--no-${option.flag}`, `Skip ${option.flag}.`);
-  }
-  for (const file of command.body?.files ?? []) {
-    leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
-  }
-  if (command.files === "pull")
-    leaf.option(
-      "--out <dir>",
-      "Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead.",
-    );
-  if (command.files === "push")
-    leaf.option(
-      "--from <dir>",
-      "The pulled head folder to push. Defaults to the current folder.",
-    );
-}
-
-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.addHelpText(
-      "after",
-      "\nRun `asteroid --version` to print the CLI 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}]`);
-    for (const [flags, text] of builtin.hiddenOptions ?? [])
-      leaf.addOption(new Flag(flags, text).hideHelp());
-    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),
-    );
-    const defaulted = defaults[0] !== undefined;
-    command.args.forEach((arg) => {
-      leaf.argument(
-        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
-        arg.description ?? "",
-      );
-    });
-    if (defaulted) {
-      const names = command.args.map((arg, i) =>
-        i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`,
-      );
-      leaf.usage(`[options] ${names.join(" ")}`);
-    }
-    const notes = [
-      defaults.some((value) => value !== undefined)
-        ? options.defaultArgNote
-        : undefined,
-      options.helpNote?.(command),
-    ].filter(Boolean);
-    if (notes.length > 0) leaf.addHelpText("after", `\n${notes.join("\n")}`);
-    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, i) => (i === 0 && defaulted ? `[${a.flag}]` : `<${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;
-
-  if (options.version && (argv[0] === "-v" || argv[0] === "--version")) {
-    return {
-      kind: "exit",
-      code: 0,
-      stdout: `${options.version}\n`,
-      stderr: "",
-    };
-  }
-  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" });
-}

package/src/reference.ts

@@ -1,195 +0,0 @@
-import type { CliCommand, Option } from "./types";
-
-export interface BuiltinCommand {
-  command: string;
-  usage: string;
-  description: string;
-  args: number;
-  arg?: string;
-  /** Flags left out of `--help` and the reference: staff only. */
-  hiddenOptions?: [string, 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,
-    hiddenOptions: [
-      [
-        "--reason <why>",
-        "Staff only. Why you need access to an organization you are not a member of, such as a ticket id. It is audited. Asked for in a terminal.",
-      ],
-      [
-        "--exit",
-        "Staff only. Revoke every staff token now and go back to your own organization.",
-      ],
-    ],
-  },
-  {
-    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) =>
-      command.files === "push" ? `[${arg.flag}]` : `<${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)`);
-  }
-  if (command.files === "pull")
-    lines.push(
-      "--out <dir>  Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead",
-    );
-  if (command.files === "push")
-    lines.push(
-      "--from <dir>  The pulled head folder to push. Defaults to the current folder",
-    );
-  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`.",
-    "At a terminal, tables show up to 6 columns and cut long cells to fit; when output is piped, they show every column in full. Use `--json` for every field.",
-    "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

@@ -1,164 +0,0 @@
-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" });
-  });
-});