@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cli-convert-automation.ts

@@ -1,335 +0,0 @@
-/**
- * `bdk convert-automation <url>` — export a Cursor Automation into a BDK
- * project.
- *
- * Fetches the automation's workflow from the backend export endpoint
- * (Bearer user API key, same credential chain as deploy), runs the pure
- * converter, writes the converted files (wx — existing files are kept),
- * fills in the init scaffold around them, and installs npm dependencies
- * (like `init`). MCP servers convert to Cursor-account connections resolved
- * at runtime (no URLs or credentials in the project; authorization is
- * managed in Cursor, dashboard → MCP). The generated project is NEVER
- * imported/executed here — it embeds server-derived data, so checking it is
- * left to an explicit `validate` next step the user runs after review.
- * Exit 0 even with warnings; nonzero only for bad args, auth/fetch
- * failures, or filesystem write failures.
- */
-
-import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { convertWorkflow } from "./convert-automation/convert-workflow.js";
-import { slugify } from "./convert-automation/slug.js";
-import type {
-  ConvertedMcpConnection,
-  ConvertWorkflowResult,
-  WorkflowJson,
-} from "./convert-automation/types.js";
-import { cursorExternalApiUrl, resolveApiKey, SIGN_IN_HINT } from "./cursor/credentials.js";
-import { AgentServeDeployClient, type AutomationExport, DeployApiError } from "./deploy-client.js";
-import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
-import {
-  formatCdCommand,
-  type InitFileEntry,
-  initProject,
-  installScaffoldDependencies,
-  isEexist,
-} from "./init-project.js";
-import { type ProjectRoot, projectPath, resolveProjectRoot } from "./project-layout.js";
-import { stdoutPalette } from "./terminal-style.js";
-
-export interface ConvertAutomationCliOptions {
-  /** Positional: automation URL or bare uuid. */
-  url?: string;
-  /** Target directory; defaults to ./<automation-name-slug>. */
-  dir?: string;
-  json?: boolean;
-  apiKey?: string;
-  /** Test seams. */
-  fetchImpl?: typeof fetch;
-  out?: (text: string) => void;
-  err?: (text: string) => void;
-  installImpl?: typeof installScaffoldDependencies;
-  cwd?: string;
-}
-
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Extract the automation uuid from a dashboard URL
- * (`/automations/<uuid>` or `/custom-agents/<uuid>`, any origin — dev
- * hosts included) or a bare uuid. Undefined when nothing matches.
- */
-export function parseAutomationRef(input: string): string | undefined {
-  const trimmed = input.trim();
-  if (UUID_PATTERN.test(trimmed)) {
-    return trimmed.toLowerCase();
-  }
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed);
-  } catch {
-    return undefined;
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    return undefined;
-  }
-  const segments = parsed.pathname.split("/").filter(s => s !== "");
-  if (segments.length !== 2) {
-    return undefined;
-  }
-  const [kind, uuid] = segments;
-  if (kind !== "automations" && kind !== "custom-agents") {
-    return undefined;
-  }
-  if (uuid === undefined || !UUID_PATTERN.test(uuid)) {
-    return undefined;
-  }
-  return uuid.toLowerCase();
-}
-
-export async function cmdConvertAutomation(options: ConvertAutomationCliOptions): Promise<number> {
-  const out = options.out ?? ((text: string) => void process.stdout.write(text));
-  const err = options.err ?? ((text: string) => void process.stderr.write(text));
-  const json = options.json === true;
-  // Failures stay machine-readable under --json (stderr keeps the prose).
-  const fail = (message: string): 1 => {
-    if (json) {
-      out(`${JSON.stringify({ ok: false, error: message })}\n`);
-    }
-    err(`${message}\n`);
-    return 1;
-  };
-
-  if (options.url === undefined || options.url.trim() === "") {
-    return fail(
-      `Usage: ${CLI} convert-automation <automation-url-or-uuid> [--dir <path>] [--json]`,
-    );
-  }
-  const uuid = parseAutomationRef(options.url);
-  if (uuid === undefined) {
-    return fail(
-      `Could not parse ${JSON.stringify(options.url)} — expected an automation URL (https://cursor.com/automations/<uuid> or .../custom-agents/<uuid>) or a bare uuid.`,
-    );
-  }
-
-  const resolved = await resolveApiKey({ apiKey: options.apiKey });
-  if (resolved === undefined) {
-    return fail(`Not signed in to Cursor. ${SIGN_IN_HINT}`);
-  }
-  const client = new AgentServeDeployClient({
-    backendUrl: cursorExternalApiUrl(),
-    apiKey: resolved.apiKey,
-    fetchImpl: options.fetchImpl,
-  });
-
-  let payload: AutomationExport;
-  try {
-    payload = await client.exportAutomation({ uuid });
-  } catch (error) {
-    if (error instanceof DeployApiError) {
-      return fail(error.message);
-    }
-    throw error;
-  }
-
-  const displayDir = options.dir ?? `./${slugify(payload.automation.name, "automation")}`;
-  const rootDir = resolve(options.cwd ?? process.cwd(), displayDir);
-  const projectRoot = resolveProjectRoot(rootDir);
-  const result = convertWorkflow({
-    automation: payload.automation,
-    workflow: payload.workflow as WorkflowJson,
-    mcpServers: payload.mcpServers,
-    exportedAt: new Date().toISOString(),
-    projectRoot,
-  });
-
-  let files: InitFileEntry[];
-  try {
-    files = await writeProjectFiles(rootDir, result, projectRoot);
-  } catch (error) {
-    return fail(`Could not write project files under ${rootDir}: ${describe(error)}`);
-  }
-
-  // Same npm install as `init`, so the printed `validate` / `dev` next steps
-  // work immediately. Failure (npm exit or spawn error) is loud but never
-  // fails the conversion.
-  const install = options.installImpl ?? installScaffoldDependencies;
-  if (!json) {
-    out("\nInstalling npm packages\n");
-  }
-  let installed: Awaited<ReturnType<typeof installScaffoldDependencies>>;
-  try {
-    installed = await install(rootDir, {
-      stdio: json ? "pipe" : "inherit",
-    });
-  } catch (error) {
-    installed = { ok: false, exitCode: -1, stderr: describe(error) };
-  }
-  if (!installed.ok && !json) {
-    const reason = installed.stderr.trim() || `exit ${installed.exitCode}`;
-    err(
-      `npm install failed (${reason}); run \`npm install\` in ${displayDir} before \`${CLI} dev\`.\n`,
-    );
-  }
-
-  if (json) {
-    out(
-      `${JSON.stringify(
-        {
-          ok: true,
-          directory: rootDir,
-          files: files.map(({ path, action }) => ({ path, action })),
-          warnings: result.warnings,
-          setupSteps: result.setupSteps,
-          installed: installed.ok,
-          installError: installed.ok
-            ? null
-            : installed.stderr.trim() || `npm install exited ${installed.exitCode}`,
-          mcpConnections: result.mcpConnections.map(connection => ({
-            name: connection.name,
-            kind: connection.kind,
-          })),
-        },
-        null,
-        2,
-      )}\n`,
-    );
-    return 0;
-  }
-
-  out(
-    renderSummary({
-      automationName: payload.automation.name,
-      displayDir,
-      rootDir,
-      cwd: options.cwd ?? process.cwd(),
-      files,
-      result,
-    }),
-  );
-  return 0;
-}
-
-/**
- * Converter files first (wx — existing files are kept), then the init
- * scaffold fills in around them with the same skip-existing semantics.
- */
-async function writeProjectFiles(
-  rootDir: string,
-  result: ConvertWorkflowResult,
-  projectRoot: ProjectRoot,
-): Promise<InitFileEntry[]> {
-  const entries: InitFileEntry[] = [];
-  const converterPaths = new Set<string>();
-  await mkdir(rootDir, { recursive: true });
-  for (const file of result.files) {
-    const path = file.path;
-    converterPaths.add(path);
-    const abs = join(rootDir, path);
-    await mkdir(dirname(abs), { recursive: true });
-    try {
-      await writeFile(abs, file.contents, { flag: "wx" });
-      entries.push({ path, action: "create" });
-    } catch (error) {
-      if (!isEexist(error)) {
-        throw error;
-      }
-      entries.push({ path, action: "exist" });
-    }
-  }
-
-  const init = await initProject({ dir: rootDir });
-
-  // Scaffold files that make sense in a fresh `init` but not in an exported
-  // automation: the default memory hook (only when the automation had memory
-  // enabled — the converter emits its own copy then) and the echo demo tool.
-  const dropPaths = new Set<string>();
-  for (const scaffoldPath of [
-    projectPath(projectRoot, "hooks/memory.ts"),
-    projectPath(projectRoot, "tools/echo.ts"),
-  ]) {
-    if (!converterPaths.has(scaffoldPath) && init.created.includes(scaffoldPath)) {
-      dropPaths.add(scaffoldPath);
-      await rm(join(rootDir, scaffoldPath));
-    }
-  }
-  for (const entry of init.files) {
-    if (converterPaths.has(entry.path) || dropPaths.has(entry.path)) {
-      continue;
-    }
-    entries.push(entry);
-  }
-  return entries;
-}
-
-function renderSummary(args: {
-  automationName: string;
-  displayDir: string;
-  rootDir: string;
-  cwd: string;
-  files: InitFileEntry[];
-  result: ConvertWorkflowResult;
-}): string {
-  const c = stdoutPalette();
-  const lines: string[] = [];
-  lines.push("");
-  lines.push(`Converted "${args.automationName}" → ${args.displayDir}`);
-  lines.push("");
-  let anyExisting = false;
-  for (const file of args.files) {
-    if (file.path.endsWith(".gitkeep")) {
-      continue;
-    }
-    anyExisting ||= file.action === "exist";
-    lines.push(c.dim(`${file.action.padStart(12)}  ${file.path}`));
-  }
-  if (anyExisting) {
-    lines.push(c.dim(`\n  "exist" files already existed and were kept as-is.`));
-  }
-
-  const warnings = args.result.warnings;
-  if (warnings.length > 0) {
-    lines.push("");
-    lines.push("Warnings:");
-    for (const warning of warnings) {
-      lines.push(`  - ${warning}`);
-    }
-  }
-
-  if (args.result.setupSteps.length > 0) {
-    lines.push("");
-    lines.push("Setup steps:");
-    for (const [index, step] of args.result.setupSteps.entries()) {
-      lines.push(`  ${index + 1}. ${step}`);
-    }
-  }
-
-  if (args.result.mcpConnections.length > 0) {
-    lines.push("");
-    lines.push("MCP connections:");
-    for (const connection of args.result.mcpConnections) {
-      lines.push(`  - ${connection.name}: ${connectionStatus(connection)}`);
-    }
-  }
-
-  lines.push("");
-  lines.push("Next steps:");
-  const cd = formatCdCommand(args.cwd, args.rootDir);
-  const steps = [...(cd === undefined ? [] : [cd]), `${CLI} validate`, `${CLI} dev`];
-  for (const [index, step] of steps.entries()) {
-    lines.push(`  ${index + 1}. ${step}`);
-  }
-  lines.push("");
-  return `${lines.join("\n")}\n`;
-}
-
-function connectionStatus(connection: ConvertedMcpConnection): string {
-  if (connection.kind === "cursorAccount") {
-    return "resolved from your Cursor account at runtime — manage authorization in Cursor (dashboard → MCP)";
-  }
-  return "needs manual setup — see the stub file and warnings above";
-}
-
-function describe(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/internal/cli-cursor.ts

@@ -1,282 +0,0 @@
-/**
- * `agent-sdk login | logout | whoami` — the Cursor account CLI.
- *
- * `login` runs the same PKCE browser flow as `cursor-agent`, then uses the
- * short-lived session exactly once to mint a named, dashboard-revocable
- * user API key. Only the key is stored (see `../cursor/credentials.ts`);
- * everything on the host — inference, cloud runtime, account MCP
- * connections — flows from it.
- */
-
-import { hostname } from "node:os";
-import {
-  CursorBackendClient,
-  CursorBackendError,
-  type CursorIdentity,
-  createUserApiKeyWithSessionToken,
-  revokeMintedUserApiKey,
-} from "./cursor/backend-client.js";
-import {
-  type ApiKeySource,
-  clearStoredCredentials,
-  credentialsFilePath,
-  cursorBackendUrl,
-  type LoginPollResult,
-  pollForLoginTokens,
-  readStoredCredentials,
-  resolveApiKey,
-  SIGN_IN_HINT,
-  startBrowserLogin,
-  writeStoredCredentials,
-} from "./cursor/credentials.js";
-import { describeError } from "./describe-error.js";
-import { CLI_COMMAND_NAME } from "./distribution.js";
-import { openBrowser } from "./open-browser.js";
-import { stderrPalette, stdoutPalette } from "./terminal-style.js";
-
-export interface CursorCliOptions {
-  /** `login --api-key <key>`: store this key instead of browser login. */
-  apiKey?: string;
-  /** `login --key-name <name>`: label for the minted key. */
-  keyName?: string;
-  json?: boolean;
-}
-
-export async function cmdLogin(options: CursorCliOptions): Promise<number> {
-  const backendUrl = cursorBackendUrl();
-  const err = stderrPalette();
-  const out = stdoutPalette();
-
-  let apiKey: string;
-  // Set only on the browser-mint path; carries what the revoke-on-failure
-  // cleanup needs (the session token that minted the key + its label).
-  let minted: { keyName: string; sessionToken: string } | undefined;
-  if (options.apiKey !== undefined && options.apiKey.trim() !== "") {
-    // Headless path: the operator brings a key (dashboard → Integrations).
-    apiKey = options.apiKey.trim();
-  } else {
-    const { loginUrl, uuid, verifier } = startBrowserLogin();
-    process.stderr.write(
-      err.dim(
-        `Opening your browser to sign in to Cursor…\n\n  ${loginUrl}\n\n(waiting for the browser sign-in to complete)\n`,
-      ),
-    );
-    openBrowser(loginUrl);
-    const login = await pollForLoginTokens({
-      uuid,
-      verifier,
-      backendUrl,
-      logger: line => process.stderr.write(`warning: ${line}\n`),
-    });
-    if (login.status !== "signed_in") {
-      process.stderr.write(`${describeLoginPollFailure(login)}\n`);
-      return 1;
-    }
-    const requestedKeyName = options.keyName?.trim();
-    const keyName =
-      requestedKeyName === undefined || requestedKeyName === ""
-        ? `${CLI_COMMAND_NAME} (${hostname()})`
-        : requestedKeyName;
-    try {
-      apiKey = await createUserApiKeyWithSessionToken({
-        backendUrl,
-        sessionToken: login.accessToken,
-        keyName,
-      });
-    } catch (error) {
-      if (error instanceof CursorBackendError && error.status === 401) {
-        // Team policy: non-admin members may be blocked from minting keys.
-        process.stderr.write(
-          `${error.message}\nYour team may restrict API key creation. Ask a team admin, or run \`${CLI_COMMAND_NAME} login --api-key <key>\` with a key from the Cursor dashboard.\n`,
-        );
-        return 1;
-      }
-      throw error;
-    }
-    minted = { keyName, sessionToken: login.accessToken };
-    process.stderr.write(err.dim(`Minted the "${keyName}" API key.\n`));
-  }
-
-  // Revoke the just-minted key when a later step fails, so a botched login
-  // never leaves an orphaned live credential (no-op on the headless path).
-  const rollbackMintedKey = async (): Promise<void> => {
-    if (minted !== undefined) {
-      await revokeMintedUserApiKey({
-        backendUrl,
-        keyName: minted.keyName,
-        apiKey,
-        sessionToken: minted.sessionToken,
-      }).catch(() => {});
-    }
-  };
-
-  // Prove the credential end-to-end (exchange + GetMe) before storing it.
-  const client = new CursorBackendClient({ backendUrl, apiKey });
-  let identity: CursorIdentity;
-  try {
-    identity = await client.getMe();
-  } catch (error) {
-    await rollbackMintedKey();
-    process.stderr.write(
-      `The API key did not authenticate against ${backendUrl}: ${describeError(error)}\n`,
-    );
-    return 1;
-  }
-
-  try {
-    await writeStoredCredentials({ backendUrl, apiKey });
-  } catch (error) {
-    await rollbackMintedKey();
-    process.stderr.write(
-      `Could not store credentials at ${credentialsFilePath()}: ${describeError(error)}\n`,
-    );
-    return 1;
-  }
-  process.stdout.write(
-    `Signed in as ${formatIdentity(identity)} (${backendUrl})\n${out.dim(
-      `Credentials stored at ${credentialsFilePath()}`,
-    )}\n`,
-  );
-  if (process.env.CURSOR_API_KEY !== undefined) {
-    process.stderr.write(
-      err.dim(
-        "note: CURSOR_API_KEY is set in this shell and takes precedence over the stored login.\n",
-      ),
-    );
-  }
-  return 0;
-}
-
-/**
- * Gate for commands that need a Cursor credential before they can do useful
- * work (interactive `init`). Already-signed-in hosts
- * (`--api-key` / `CURSOR_API_KEY` / `CURSOR_API_KEY_FILE` / stored login) return immediately.
- * An interactive host runs {@link cmdLogin}; a non-interactive one (CI,
- * Docker) fails fast with {@link SIGN_IN_HINT}
- * instead of polling a browser that will never open.
- */
-export async function ensureCursorLogin(
-  options: {
-    apiKey?: string;
-    /**
-     * Run the browser login flow when unsigned. Defaults to stderr being a
-     * TTY.
-     */
-    interactive?: boolean;
-    /** Test seam. */
-    login?: (options: CursorCliOptions) => Promise<number>;
-  } = {},
-): Promise<number> {
-  const resolved = await resolveApiKey({ apiKey: options.apiKey });
-  if (resolved !== undefined) {
-    return 0;
-  }
-  const interactive = options.interactive ?? process.stderr.isTTY === true;
-  if (!interactive) {
-    process.stderr.write(`Not signed in to Cursor. ${SIGN_IN_HINT}\n`);
-    return 1;
-  }
-  process.stdout.write("Signing you in to Cursor\n\n");
-  const login = options.login ?? cmdLogin;
-  return login({});
-}
-
-export async function cmdLogout(): Promise<number> {
-  const stored = await readStoredCredentials();
-  const removed = await clearStoredCredentials();
-  if (!removed || stored === undefined) {
-    process.stdout.write("No stored Cursor credentials.\n");
-    return 0;
-  }
-  process.stdout.write(
-    `Signed out (removed ${credentialsFilePath()}). The API key still exists — revoke it in the Cursor dashboard if it should stop working.\n`,
-  );
-  return 0;
-}
-
-export async function cmdWhoami(options: CursorCliOptions): Promise<number> {
-  const resolved = await resolveApiKey();
-  if (resolved === undefined) {
-    process.stderr.write(`Not signed in to Cursor. ${SIGN_IN_HINT}\n`);
-    return 1;
-  }
-  const client = new CursorBackendClient({
-    backendUrl: resolved.backendUrl,
-    apiKey: resolved.apiKey,
-  });
-  let identity: CursorIdentity;
-  try {
-    identity = await client.getMe();
-  } catch (error) {
-    process.stderr.write(
-      `The ${describeSource(resolved.source)} did not authenticate against ${resolved.backendUrl}: ${describeError(error)}\n`,
-    );
-    return 1;
-  }
-  if (options.json === true) {
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          email: identity.email ?? null,
-          authId: identity.authId ?? null,
-          teamName: identity.teamName ?? null,
-          backendUrl: resolved.backendUrl,
-          credentialSource: resolved.source,
-        },
-        null,
-        2,
-      )}\n`,
-    );
-    return 0;
-  }
-  process.stdout.write(
-    `${formatIdentity(identity)}\n  backend:    ${resolved.backendUrl}\n  credential: ${describeSource(resolved.source)}\n`,
-  );
-  return 0;
-}
-
-function formatIdentity(identity: CursorIdentity): string {
-  const name = [identity.firstName, identity.lastName]
-    .filter(part => part !== undefined && part !== "")
-    .join(" ");
-  const email = identity.email ?? identity.authId ?? "(unknown user)";
-  const team = identity.teamName === undefined ? "" : ` — team ${identity.teamName}`;
-  return name === "" ? `${email}${team}` : `${name} <${email}>${team}`;
-}
-
-function describeSource(source: ApiKeySource): string {
-  switch (source) {
-    case "option":
-      return "explicit --api-key / serve({ apiKey })";
-    case "env":
-      return "CURSOR_API_KEY environment variable";
-    case "file":
-      return "CURSOR_API_KEY_FILE (task bind)";
-    case "service-account":
-      return "CURSOR_SERVICE_ACCOUNT_KEY environment variable";
-    case "login":
-      return `stored login (${credentialsFilePath()})`;
-  }
-}
-
-/**
- * Never report a backend failure as a timeout: a wrong-verb poll used to print
- * "Login timed out or was cancelled" ~200ms in, which reads as "you were too
- * slow" and hides the actual 404.
- */
-function describeLoginPollFailure(
-  result: Exclude<LoginPollResult, { status: "signed_in" }>,
-): string {
-  switch (result.status) {
-    case "cancelled":
-      return "Login cancelled.";
-    case "timed_out":
-      return `Login timed out — the browser sign-in was never completed. Run \`${CLI_COMMAND_NAME} login\` to try again.`;
-    case "failed":
-      return [
-        `Login failed: ${result.message}`,
-        "This is not a timeout — the sign-in never got a chance to complete.",
-        `Sign in without the browser flow with \`${CLI_COMMAND_NAME} login --api-key <key>\` (Cursor dashboard → Integrations).`,
-      ].join("\n");
-  }
-}