@asteroidai/cli 0.0.0 → 1.8.193

package/src/run.test.ts

@@ -0,0 +1,280 @@
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { CredentialStore } from "./auth/store";
+import { readEnv, saveConfig } from "./config";
+import { COMMANDS } from "./generated/commands";
+import { renderReference } from "./reference";
+import { type Deps, run } from "./run";
+
+interface Call {
+  url: string;
+  init: RequestInit;
+}
+
+function jwt(claims: Record<string, unknown>): string {
+  const part = (value: unknown) =>
+    Buffer.from(JSON.stringify(value)).toString("base64url");
+  return `${part({ alg: "none" })}.${part(claims)}.sig`;
+}
+
+function harness(
+  env: Record<string, string>,
+  respond: (call: Call) => Response,
+) {
+  const configDir = mkdtempSync(join(tmpdir(), "asteroid-cli-"));
+  const calls: Call[] = [];
+  const out: string[] = [];
+  const err: string[] = [];
+  const deps: Deps = {
+    env: readEnv({ ASTEROID_CONFIG_DIR: configDir, ...env }),
+    cwd: configDir,
+    fetch: (async (url: string, init: RequestInit) => {
+      const call = { url: String(url), init };
+      calls.push(call);
+      return respond(call);
+    }) as typeof fetch,
+    stdout: (text) => out.push(text),
+    stderr: (text) => err.push(text),
+    writeBytes: () => undefined,
+  };
+  return { deps, calls, out, err, configDir };
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+
+beforeEach(() => {
+  process.env.ASTEROID_NO_KEYCHAIN = "1";
+});
+
+describe("run", () => {
+  it("sends the API key and prints a table", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({
+        items: [{ id: "w1", name: "Fill form" }],
+        page: 1,
+        pageSize: 50,
+        total: 1,
+      }),
+    );
+    const code = await run(["workflow", "list"], h.deps);
+    expect(code).toBe(0);
+    expect(h.calls[0].url).toBe(
+      "https://odyssey.asteroid.ai/agents/v2/workflows",
+    );
+    expect(
+      (h.calls[0].init.headers as Record<string, string>)["X-Api-Key"],
+    ).toBe("sk_test");
+    expect(h.out.join("")).toContain("Fill form");
+  });
+
+  it("prints the problem detail and exits 1 on an API error", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({ detail: "Execution not found", status: 404 }, 404),
+    );
+    const code = await run(["execution", "get", "e1"], h.deps);
+    expect(code).toBe(1);
+    expect(h.err.join("")).toContain("404: Execution not found");
+  });
+
+  it("exits 2 on a usage error without calling the API", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () => json({}));
+    expect(await run(["workflow", "get"], h.deps)).toBe(2);
+    expect(await run(["nope"], h.deps)).toBe(2);
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("prints raw JSON with --json and names the org on a write", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({ id: "w1" }),
+    );
+    await run(["workflow", "rename", "w1", "--name", "New", "--json"], h.deps);
+    expect(JSON.parse(h.out.join(""))).toEqual({ id: "w1" });
+    expect(h.err.join("")).toContain("Acting in the API key's organization.");
+    expect(JSON.parse(String(h.calls[0].init.body))).toEqual({ name: "New" });
+  });
+
+  it("mints an org token from the stored sign-in and caches it", async () => {
+    const access = jwt({
+      exp: Date.now() / 1000 + 300,
+      org_id: "org_A",
+      org: { id: "uuid-a", name: "Acme" },
+    });
+    const h = harness({}, (call) => {
+      if (call.url.includes("workos")) {
+        expect(
+          Object.fromEntries(call.init.body as URLSearchParams),
+        ).toMatchObject({
+          grant_type: "refresh_token",
+          refresh_token: "r1",
+          organization_id: "org_A",
+        });
+        return json({
+          access_token: access,
+          refresh_token: "r2",
+          organization_id: "org_A",
+        });
+      }
+      return json({ items: [], page: 1, pageSize: 50, total: 0 });
+    });
+    h.deps.env.workosApiUrl = "https://workos.test";
+    const store = new CredentialStore(h.deps.env);
+    await store.writeLogin({ refreshToken: "r1" });
+    saveConfig(h.deps.env, { org: { workosId: "org_A" } });
+
+    const codes = await Promise.all([
+      run(["workflow", "list"], h.deps),
+      run(["workflow", "list"], h.deps),
+    ]);
+    expect(codes).toEqual([0, 0]);
+    expect(await run(["workflow", "list"], h.deps)).toBe(0);
+
+    const workosCalls = h.calls.filter((c) => c.url.includes("workos"));
+    expect(workosCalls).toHaveLength(1);
+    expect(
+      (h.calls.at(-1)!.init.headers as Record<string, string>).Authorization,
+    ).toBe(`Bearer ${access}`);
+    expect((await store.readLogin())?.refreshToken).toBe("r2");
+    const config = JSON.parse(
+      readFileSync(join(h.configDir, "config.json"), "utf8"),
+    );
+    expect(config.org).toEqual({
+      workosId: "org_A",
+      id: "uuid-a",
+      name: "Acme",
+    });
+  });
+
+  it("asks for an org when none is set", async () => {
+    const h = harness({}, () => json({}));
+    await new CredentialStore(h.deps.env).writeLogin({ refreshToken: "r1" });
+    expect(await run(["workflow", "list"], h.deps)).toBe(1);
+    expect(h.err.join("")).toContain("asteroid use <org>");
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("sends an SSO or MFA org back to login", async () => {
+    const h = harness({}, () =>
+      json({ error: "sso_required", error_description: "SSO required" }, 400),
+    );
+    h.deps.env.workosApiUrl = "https://workos.test";
+    await new CredentialStore(h.deps.env).writeLogin({ refreshToken: "r1" });
+    saveConfig(h.deps.env, { org: { workosId: "org_A", name: "Acme" } });
+    expect(await run(["workflow", "list"], h.deps)).toBe(1);
+    expect(h.err.join("")).toContain("requires SSO or MFA");
+  });
+
+  it("asks to sign in when there is no credential", async () => {
+    const h = harness({}, () => json({}));
+    expect(await run(["workflow", "list"], h.deps)).toBe(1);
+    expect(h.err.join("")).toContain("asteroid login");
+  });
+});
+
+describe("guards", () => {
+  it("refuses --org with an API key", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () => json({}));
+    expect(await run(["workflow", "list", "--org", "Acme"], h.deps)).toBe(2);
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("rejects extra arguments and unknown flags on account commands", async () => {
+    const h = harness({}, () => json({}));
+    expect(await run(["use", "a", "b"], h.deps)).toBe(2);
+    expect(await run(["logout", "--typo", "x"], h.deps)).toBe(2);
+  });
+
+  it("drops the API key when a download redirects to another host", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.url.startsWith("https://odyssey")
+        ? new Response(null, {
+            status: 303,
+            headers: { location: "https://storage.test/file" },
+          })
+        : new Response("bytes", { status: 200 }),
+    );
+    expect(
+      await run(["execution", "file", "download", "e1", "f1"], h.deps),
+    ).toBe(0);
+    const download = h.calls[1];
+    expect(download.url).toBe("https://storage.test/file");
+    expect(
+      (download.init.headers as Record<string, string>)["X-Api-Key"],
+    ).toBeUndefined();
+  });
+
+  it("keeps the method and body on a 307", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.url.endsWith("/validate")
+        ? new Response(null, {
+            status: 307,
+            headers: { location: "/agents/v2/schema/validate2" },
+          })
+        : json({ valid: true }),
+    );
+    await run(["schema", "validate", "--schema", "{}"], h.deps);
+    expect(h.calls[1].init.method).toBe("POST");
+    expect(h.calls[1].init.body).toBe('{"schema":{}}');
+    expect(
+      (h.calls[1].init.headers as Record<string, string>)["X-Api-Key"],
+    ).toBe("sk_test");
+  });
+
+  it("renders nested object lists as a table", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({ tools: [{ name: "go_to_url", capability: "web" }] }),
+    );
+    await run(["tool", "list"], h.deps);
+    expect(h.out.join("")).toContain("go_to_url");
+  });
+});
+
+describe("terminal safety", () => {
+  it("refuses to print a download to a terminal", async () => {
+    const h = harness(
+      { ASTEROID_API_KEY: "sk_test" },
+      () => new Response("bytes"),
+    );
+    h.deps.stdoutIsTTY = true;
+    expect(await run(["execution", "recording", "e1"], h.deps)).toBe(2);
+    expect(h.err.join("")).toContain("--output");
+  });
+
+  it("cleans control characters out of API errors", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({ detail: "bad\u001b[2Jthing" }, 400),
+    );
+    await run(["execution", "get", "e1"], h.deps);
+    expect(h.err.join("")).toContain("badthing");
+    expect(h.err.join("")).not.toContain("\u001b");
+  });
+
+  it("fills a body organization from an API key's whoami", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.url.endsWith("/users/v2/whoami")
+        ? json({ organizationId: "org-from-key" })
+        : json({ id: "w1" }),
+    );
+    expect(await run(["workflow", "create", "--name", "W"], h.deps)).toBe(0);
+    expect(JSON.parse(String(h.calls.at(-1)!.init.body))).toMatchObject({
+      organizationId: "org-from-key",
+      name: "W",
+    });
+  });
+});
+
+describe("reference", () => {
+  it("matches the generated agent-docs page", () => {
+    const page = readFileSync(
+      new URL("../../../docs/cli/reference.mdx", import.meta.url),
+      "utf8",
+    );
+    expect(page).toBe(renderReference(COMMANDS));
+  });
+});

package/src/run.ts

@@ -0,0 +1,178 @@
+import { writeFileSync } from "node:fs";
+
+import { login, logout, orgs, use, whoami } from "./account";
+import { type Parsed, UsageError } from "./args";
+import { type Auth, AuthError, resolveAuth } from "./auth/credentials";
+import { WorkosError } from "./auth/workos";
+import { type Env, loadConfig, orgLabel, requestedOrg } from "./config";
+import { COMMANDS } from "./generated/commands";
+import { ApiError, send, VERSION } from "./http";
+import { clean, render } from "./output";
+import { parseInvocation } from "./program";
+import { BUILTINS } from "./reference";
+import { buildRequest } from "./request";
+import type { CliCommand } from "./types";
+import type { Ui } from "./ui";
+
+export interface Deps {
+  env: Env;
+  cwd: string;
+  fetch: typeof fetch;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  writeBytes: (bytes: Uint8Array) => void;
+  stdoutIsTTY?: boolean;
+  styled?: boolean;
+  ui?: Ui;
+  openUrl?: (url: string) => void;
+}
+
+function rejectOrgWithApiKey(deps: Deps, flagOrg: string | undefined) {
+  if (deps.env.apiKey && (flagOrg || deps.env.org)) {
+    throw new UsageError(
+      "ASTEROID_API_KEY acts in its own organization. Unset --org and ASTEROID_ORG, or sign in with `asteroid login`.",
+    );
+  }
+}
+
+async function runBuiltin(
+  name: string,
+  parsed: Parsed,
+  deps: Deps,
+): Promise<number> {
+  if (name !== "login" && name !== "logout")
+    rejectOrgWithApiKey(deps, parsed.org);
+  switch (name) {
+    case "login":
+      return login(deps);
+    case "logout":
+      return logout(deps);
+    case "orgs":
+      return orgs(deps, parsed.org, parsed.json);
+    case "complete":
+      throw new UsageError(
+        "run `asteroid complete <shell>` to print a completion script",
+      );
+    case "use":
+      return use(deps, parsed.positionals[0]);
+    default:
+      return whoami(deps, parsed.org, parsed.json);
+  }
+}
+
+async function credentialOrganization(
+  deps: Deps,
+  auth: Auth,
+): Promise<string | undefined> {
+  if (auth.org?.id) return auth.org.id;
+  const response = await send(
+    deps.env.apiUrl,
+    auth,
+    { method: "GET", path: "/users/v2/whoami", query: new URLSearchParams() },
+    false,
+    deps.fetch,
+  );
+  return (response.json as { organizationId?: string } | undefined)
+    ?.organizationId;
+}
+
+async function runCommand(
+  command: CliCommand,
+  parsed: Parsed,
+  deps: Deps,
+): Promise<number> {
+  const needsOrganization = command.body?.credentialOrganization === true;
+  let request = needsOrganization
+    ? undefined
+    : await buildRequest(command, parsed);
+  rejectOrgWithApiKey(deps, parsed.org);
+  const config = loadConfig(deps.env);
+  const auth = await resolveAuth(
+    deps.env,
+    config,
+    requestedOrg(parsed.org, deps.env, deps.cwd, config),
+    deps.fetch,
+  );
+  request ??= await buildRequest(command, parsed, {
+    organizationId: await credentialOrganization(deps, auth),
+  });
+  if (!command.readOnly) {
+    const org =
+      auth.kind === "api-key"
+        ? "the API key's organization"
+        : auth.org
+          ? orgLabel(auth.org)
+          : "your default organization";
+    deps.stderr(`Acting in ${org}.\n`);
+  }
+
+  const response = await send(
+    deps.env.apiUrl,
+    auth,
+    request,
+    command.binary,
+    deps.fetch,
+  );
+  if (response.bytes) {
+    if (parsed.output) {
+      writeFileSync(parsed.output, response.bytes);
+      deps.stderr(
+        `Wrote ${response.bytes.length} bytes to ${parsed.output}.\n`,
+      );
+    } else if (deps.stdoutIsTTY) {
+      throw new UsageError(
+        "refusing to print binary data to a terminal. Pass --output <file> or redirect stdout.",
+      );
+    } else deps.writeBytes(response.bytes);
+    return 0;
+  }
+  if (response.status === 204) {
+    if (!parsed.json) deps.stderr("Done.\n");
+    return 0;
+  }
+  if (response.json !== undefined) {
+    deps.stdout(
+      `${parsed.json ? JSON.stringify(response.json, null, 2) : render(response.json, { styled: deps.styled })}\n`,
+    );
+    return 0;
+  }
+  if (response.text) deps.stdout(`${clean(response.text)}\n`);
+  return 0;
+}
+
+const DESCRIPTION =
+  "The Asteroid CLI. Sign in with `asteroid login`, or set ASTEROID_API_KEY.";
+
+export async function run(argv: string[], deps: Deps): Promise<number> {
+  try {
+    const invocation = await parseInvocation(argv, {
+      commands: COMMANDS,
+      builtins: BUILTINS,
+      version: VERSION,
+      description: DESCRIPTION,
+    });
+    if (invocation.kind === "exit") {
+      if (invocation.stdout) deps.stdout(invocation.stdout);
+      if (invocation.stderr) deps.stderr(invocation.stderr);
+      return invocation.code;
+    }
+    if (invocation.kind === "builtin") {
+      return await runBuiltin(invocation.name, invocation.parsed, deps);
+    }
+    return await runCommand(invocation.command, invocation.parsed, deps);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      deps.stderr(`asteroid: ${clean(error.message)}\n`);
+      return 2;
+    }
+    if (error instanceof ApiError) {
+      deps.stderr(`asteroid: ${error.status}: ${clean(error.message)}\n`);
+      return 1;
+    }
+    if (error instanceof AuthError || error instanceof WorkosError) {
+      deps.stderr(`asteroid: ${clean(error.message)}\n`);
+      return 1;
+    }
+    throw error;
+  }
+}

package/src/types.ts

@@ -0,0 +1,42 @@
+export type ValueType =
+  | "string"
+  | "integer"
+  | "number"
+  | "boolean"
+  | "string[]"
+  | "integer[]"
+  | "number[]"
+  | "json";
+
+export interface Option {
+  name: string;
+  flag: string;
+  type: ValueType;
+  required: boolean;
+  description?: string;
+  enum?: string[];
+  explode?: boolean;
+}
+
+export interface BodySpec {
+  required: boolean;
+  contentType: "application/json" | "multipart/form-data";
+  fields: Option[];
+  files: string[];
+  credentialOrganization: boolean;
+}
+
+export interface CliCommand {
+  command: string;
+  tool: string;
+  title: string;
+  description: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  args: Option[];
+  query: Option[];
+  body?: BodySpec;
+  binary: boolean;
+  readOnly: boolean;
+  destructive: boolean;
+}

package/src/ui.ts

@@ -0,0 +1,30 @@
+import * as clack from "@clack/prompts";
+
+export interface Choice {
+  value: string;
+  label: string;
+}
+
+export interface Ui {
+  select(message: string, choices: Choice[]): Promise<string | undefined>;
+  wait<T>(message: string, done: string, work: Promise<T>): Promise<T>;
+}
+
+export const clackUi: Ui = {
+  async select(message, choices) {
+    const value = await clack.select({ message, options: choices });
+    return clack.isCancel(value) ? undefined : value;
+  },
+  async wait(message, done, work) {
+    const spinner = clack.spinner();
+    spinner.start(message);
+    try {
+      const result = await work;
+      spinner.stop(done);
+      return result;
+    } catch (error) {
+      spinner.stop(message);
+      throw error;
+    }
+  },
+};