@cursor/july 0.1.32 → 0.1.34

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

@@ -0,0 +1,352 @@
+/**
+ * `agent-serve convert-automation <url>` — export a Cursor Automation into
+ * an agentkit 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 {
+  type ConvertedMcpConnection,
+  type ConvertWorkflowResult,
+  convertWorkflow,
+  type WorkflowJson,
+} from "./convert-automation/index.js";
+import { slugify } from "./convert-automation/slug.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 { 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 result = convertWorkflow({
+    automation: payload.automation,
+    workflow: payload.workflow as WorkflowJson,
+    mcpServers: payload.mcpServers,
+    exportedAt: new Date().toISOString(),
+  });
+
+  const displayDir =
+    options.dir ?? `./${slugify(payload.automation.name, "automation")}`;
+  const rootDir = resolve(options.cwd ?? process.cwd(), displayDir);
+
+  let files: InitFileEntry[];
+  try {
+    files = await writeProjectFiles(rootDir, result);
+  } 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
+): Promise<InitFileEntry[]> {
+  const entries: InitFileEntry[] = [];
+  const converterPaths = new Set<string>();
+  await mkdir(rootDir, { recursive: true });
+  for (const file of result.files) {
+    converterPaths.add(file.path);
+    const abs = join(rootDir, file.path);
+    await mkdir(dirname(abs), { recursive: true });
+    try {
+      await writeFile(abs, file.contents, { flag: "wx" });
+      entries.push({ path: file.path, action: "create" });
+    } catch (error) {
+      if (!isEexist(error)) {
+        throw error;
+      }
+      entries.push({ path: file.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 ["agent/hooks/memory.ts", "agent/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-deploy.ts

@@ -1345,7 +1345,7 @@ function promptHidden(
 }
 
 /** Buffered line reader over a piped stream; undefined once it ends. */
-function createLineReader(
+export function createLineReader(
   stream: NodeJS.ReadableStream
 ): () => Promise<string | undefined> {
   let buffer = "";

package/src/internal/cli-mcp-oauth.ts

@@ -96,30 +96,77 @@ export async function cmdMcpOauth(
     return 1;
   }
 
-  out(
-    `${LOG_PREFIX} Authorizing "${options.connection}" (${transport.url})…\n`
-  );
+  const flow = await authorizeHostMcpOauth({
+    connection: options.connection,
+    url: transport.url,
+    type: transport.type === "sse" ? "sse" : "http",
+    headers: transport.headers,
+    out,
+    err,
+  });
+  if (!flow.ok) {
+    return 1;
+  }
+
+  if (options.store !== true) {
+    return 0;
+  }
+  return storeOauthSecrets({
+    connection: options.connection,
+    dir: options.dir,
+    slug: options.slug,
+    team: options.team,
+    apiKey: options.apiKey,
+    tokens: flow.tokens,
+    clientId: flow.clientId,
+    err,
+    out,
+  });
+}
+
+export interface HostMcpOauthArgs {
+  /** Connection name — the local token-store identifier. */
+  connection: string;
+  url: string;
+  type?: "http" | "sse";
+  headers?: Record<string, string>;
+  out: (text: string) => void;
+  err: (text: string) => void;
+}
+
+export type HostMcpOauthResult =
+  | { ok: true; tokens: OAuthTokens | undefined; clientId: string | undefined }
+  | { ok: false };
+
+/**
+ * The interactive host-OAuth browser flow against an MCP server URL. Takes
+ * the transport metadata directly so callers that already hold it never have
+ * to load the authored project to authorize.
+ */
+export async function authorizeHostMcpOauth(
+  args: HostMcpOauthArgs
+): Promise<HostMcpOauthResult> {
+  const { connection, out, err } = args;
+  out(`${LOG_PREFIX} Authorizing "${connection}" (${args.url})…\n`);
 
   let authorizationUrl: URL | undefined;
   const provider = await createHostMcpOAuthProvider({
-    identifier: options.connection,
-    resourceUrl: transport.url,
+    identifier: connection,
+    resourceUrl: args.url,
     onRedirect: (url) => {
       authorizationUrl = url;
     },
   });
 
   const client = new Client({ name: "agent-sdk-mcp-oauth", version: "0.1.0" });
-  const url = new URL(transport.url);
+  const url = new URL(args.url);
   const requestInit =
-    transport.headers === undefined
-      ? undefined
-      : { headers: transport.headers };
+    args.headers === undefined ? undefined : { headers: args.headers };
 
   const makeTransport = ():
     | StreamableHTTPClientTransport
     | SSEClientTransport => {
-    if (transport.type === "sse") {
+    if (args.type === "sse") {
       return new SSEClientTransport(url, {
         authProvider: provider,
         requestInit,
@@ -135,15 +182,15 @@ export async function cmdMcpOauth(
   let authorized = false;
   try {
     await client.connect(mcpTransport);
-    out(`${LOG_PREFIX} "${options.connection}" already authorized.\n`);
+    out(`${LOG_PREFIX} "${connection}" already authorized.\n`);
     await client.close().catch(() => undefined);
     authorized = true;
   } catch (error) {
     if (!(error instanceof UnauthorizedError)) {
       err(
-        `${LOG_PREFIX} Failed to connect to "${options.connection}": ${describe(error)}\n`
+        `${LOG_PREFIX} Failed to connect to "${connection}": ${describe(error)}\n`
       );
-      return 1;
+      return { ok: false };
     }
   }
 
@@ -153,7 +200,7 @@ export async function cmdMcpOauth(
       err(
         `${LOG_PREFIX} Auth required but no authorization URL was provided.\n`
       );
-      return 1;
+      return { ok: false };
     }
 
     out(`${LOG_PREFIX} Open if needed:\n  ${redirect.toString()}\n`);
@@ -165,14 +212,14 @@ export async function cmdMcpOauth(
       callback = await waitForMcpOAuthCallback();
     } catch (error) {
       err(`${LOG_PREFIX} OAuth callback failed: ${describe(error)}\n`);
-      return 1;
+      return { ok: false };
     }
 
     try {
       await mcpTransport.finishAuth(callback.code);
     } catch (error) {
       err(`${LOG_PREFIX} Token exchange failed: ${describe(error)}\n`);
-      return 1;
+      return { ok: false };
     }
 
     mcpTransport = makeTransport();
@@ -180,31 +227,22 @@ export async function cmdMcpOauth(
       await client.connect(mcpTransport);
       const tools = await client.listTools();
       out(
-        `${LOG_PREFIX} Authorized "${options.connection}" (${tools.tools.length} tools). Local tokens in the agent-serve config dir.\n`
+        `${LOG_PREFIX} Authorized "${connection}" (${tools.tools.length} tools). Local tokens in the agent-serve config dir.\n`
       );
       await client.close().catch(() => undefined);
     } catch (error) {
       err(
-        `${LOG_PREFIX} Reconnect failed: ${describe(error)}. Re-run \`${CLI} mcp oauth ${options.connection}\`.\n`
+        `${LOG_PREFIX} Reconnect failed: ${describe(error)}. Re-run \`${CLI} mcp oauth ${connection}\`.\n`
       );
-      return 1;
+      return { ok: false };
     }
   }
 
-  if (options.store !== true) {
-    return 0;
-  }
-  return storeOauthSecrets({
-    connection: options.connection,
-    dir: options.dir,
-    slug: options.slug,
-    team: options.team,
-    apiKey: options.apiKey,
+  return {
+    ok: true,
     tokens: provider.tokens(),
     clientId: provider.clientInformation()?.client_id,
-    err,
-    out,
-  });
+  };
 }
 
 /**