@cursor/july 0.1.2 → 0.1.3

package/src/internal/cli-deploy.ts

@@ -13,7 +13,7 @@ import { basename, resolve } from "node:path";
 import type { AgentHostingOptions } from "../types.js";
 import { CursorBackendClient } from "./cursor/backend-client.js";
 import {
-  cursorBackendUrl,
+  cursorExternalApiUrl,
   resolveApiKey,
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
@@ -31,29 +31,63 @@ import {
   TERMINAL_DEPLOY_STATUSES,
   validateDeploymentSlug,
 } from "./deploy-client.js";
-import { isAgentProjectDir, loadAgentProject } from "./discovery.js";
+import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
+import {
+  type ChildAgentDir,
+  isAgentProjectDir,
+  listChildAgentDirs,
+  loadAgentProject,
+} from "./discovery.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import {
   isValidCursorEventRepo,
   validateSettableSecretName,
 } from "./hosting.js";
+import { stderrPalette } from "./terminal-style.js";
 
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 const DEFAULT_DEPLOY_TIMEOUT_MS = 10 * 60 * 1000;
 
+/** One agent directory selected for deploy (single or multi-agent parent). */
+export type DeployTarget = ChildAgentDir;
+
+/**
+ * Interactive / test seam: pick which agents under a multi-agent parent to
+ * deploy. Return `null` to cancel.
+ */
+export type ChooseDeployTargets = (
+  agents: readonly DeployTarget[]
+) => Promise<DeployTarget[] | null>;
+
 export interface DeployCliOptions {
   dir?: string;
   slug?: string;
+  /**
+   * deploy `--all`: when `--dir` is a multi-agent parent, deploy every
+   * child agent (skips the interactive picker).
+   */
+  all?: boolean;
   /** `--team <id>`; resolved from the account when omitted. */
   team?: string;
   json?: boolean;
   noWait?: boolean;
   apiKey?: string;
-  /** deploy `--repo <url>`: https git repo the control plane builds from. */
+  /**
+   * deploy `--repo <url>`: https git repo the control plane builds from.
+   * Optional — inferred from `git remote origin` when omitted inside an
+   * agent project checkout.
+   */
   repo?: string;
-  /** deploy `--ref <ref>`: git ref (defaults to the default branch server-side). */
+  /**
+   * deploy `--ref <ref>`: git ref to build. Optional — inferred from the
+   * current branch (or HEAD SHA if detached) when omitted; otherwise the
+   * server uses the repo's default branch.
+   */
   ref?: string;
-  /** deploy `--path <agentPath>`: agent directory relative to the repo root. */
+  /**
+   * deploy `--path <agentPath>`: agent directory relative to the repo root.
+   * Optional — inferred from `--dir` vs the git toplevel when omitted.
+   */
   path?: string;
   /** deploy `--cursor-events-repo <owner/name>` (repeatable). */
   cursorEventsRepos?: string[];
@@ -61,6 +95,10 @@ export interface DeployCliOptions {
   allowDomains?: string[];
   /** Test seams. */
   fetchImpl?: typeof fetch;
+  /** Inject git probing for deploy source inference (tests). */
+  git?: GitRunner;
+  /** Inject the multi-agent picker (tests / non-interactive hosts). */
+  chooseTargets?: ChooseDeployTargets;
   pollIntervalMs?: number;
   timeoutMs?: number;
   out?: (text: string) => void;
@@ -86,15 +124,27 @@ interface DeployCliContext {
   err: (text: string) => void;
 }
 
+export interface ResolveDeployAuthOptions {
+  team?: string;
+  apiKey?: string;
+  fetchImpl?: typeof fetch;
+  /** Quiet team-resolution chatter (default: write to stderr). */
+  err?: (text: string) => void;
+}
+
+export interface ResolvedDeployAuth {
+  client: AgentServeDeployClient;
+  teamId: number;
+}
+
 /**
- * Shared preamble: credentials → client → team id. Returns an exit code
- * (with the error already rendered) when resolution fails.
+ * Credentials → deploy client → team id. Shared by deploy commands and
+ * `--prod` AX routing. Returns an exit code (error already rendered) on
+ * failure.
  */
-async function prepare(
-  options: DeployCliOptions
-): Promise<DeployCliContext | number> {
-  const out =
-    options.out ?? ((text: string) => void process.stdout.write(text));
+export async function resolveDeployAuth(
+  options: ResolveDeployAuthOptions
+): Promise<ResolvedDeployAuth | number> {
   const err =
     options.err ?? ((text: string) => void process.stderr.write(text));
 
@@ -105,12 +155,13 @@ async function prepare(
     err(`Not signed in to Cursor. ${SIGN_IN_HINT}\n`);
     return 1;
   }
+  // The deployment management routes live on the external API host
+  // (api.cursor.com), not the default backend (api2.cursor.sh) — see
+  // cursorExternalApiUrl. GetMe below stays on the resolved backend.
   const client = new AgentServeDeployClient({
-    backendUrl: resolved.backendUrl,
+    backendUrl: cursorExternalApiUrl(),
     apiKey: resolved.apiKey,
-    ...(options.fetchImpl === undefined
-      ? {}
-      : { fetchImpl: options.fetchImpl }),
+    fetchImpl: options.fetchImpl,
   });
 
   let teamId: number;
@@ -124,9 +175,7 @@ async function prepare(
     const account = new CursorBackendClient({
       backendUrl: resolved.backendUrl,
       apiKey: resolved.apiKey,
-      ...(options.fetchImpl === undefined
-        ? {}
-        : { fetchImpl: options.fetchImpl }),
+      fetchImpl: options.fetchImpl,
     });
     let identity: Awaited<ReturnType<CursorBackendClient["getMe"]>>;
     try {
@@ -144,16 +193,44 @@ async function prepare(
       return 1;
     }
     teamId = identity.teamId;
+    const dim = stderrPalette().dim;
     err(
-      `Using team ${teamId}${
-        identity.teamName === undefined ? "" : ` (${identity.teamName})`
-      } — the account's team; pass --team to override.\n`
+      `${dim(
+        `Using team ${teamId}${
+          identity.teamName === undefined ? "" : ` (${identity.teamName})`
+        } — the account's team; pass --team to override.`
+      )}\n`
     );
   }
 
+  return { client, teamId };
+}
+
+/**
+ * Shared preamble: credentials → client → team id. Returns an exit code
+ * (with the error already rendered) when resolution fails.
+ */
+async function prepare(
+  options: DeployCliOptions
+): Promise<DeployCliContext | number> {
+  const out =
+    options.out ?? ((text: string) => void process.stdout.write(text));
+  const err =
+    options.err ?? ((text: string) => void process.stderr.write(text));
+
+  const auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+    err,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+
   return {
-    client,
-    teamId,
+    client: auth.client,
+    teamId: auth.teamId,
     json: options.json === true,
     noWait: options.noWait === true,
     pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
@@ -172,30 +249,308 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
   if (typeof ctx === "number") {
     return ctx;
   }
+
+  const targets = await resolveDeployTargets(options, ctx);
+  if (typeof targets === "number") {
+    return targets;
+  }
+
+  // --path is per-agent (relative to the repo root). When deploying several
+  // agents, ignore a shared --path so each target can infer its own path.
+  let deployOptions = options;
+  if (targets.length > 1 && options.path !== undefined) {
+    if (!ctx.json) {
+      ctx.err(
+        `warning: ignoring --path ${JSON.stringify(options.path)} for a multi-agent deploy; each agent infers its own path from git.\n`
+      );
+    }
+    deployOptions = { ...options, path: undefined };
+  }
+
+  if (targets.length === 1) {
+    return deployOne(ctx, deployOptions, targets[0]!);
+  }
+
+  // Multi-agent batch: deploy sequentially; --json emits an array.
+  const jsonResults: unknown[] = [];
+  let failures = 0;
+  for (const [index, target] of targets.entries()) {
+    if (!ctx.json) {
+      ctx.err(
+        `\n=== [${index + 1}/${targets.length}] Deploying ${target.slug} ===\n`
+      );
+    }
+    const before = jsonResults.length;
+    const code = await deployOne(ctx, deployOptions, target, {
+      jsonCollect: ctx.json ? jsonResults : undefined,
+    });
+    if (code !== 0) {
+      failures += 1;
+      if (ctx.json && jsonResults.length === before) {
+        jsonResults.push({ slug: target.slug, error: "deploy failed" });
+      }
+    }
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(jsonResults, null, 2)}\n`);
+  } else if (failures > 0) {
+    ctx.err(`\n${failures} of ${targets.length} deploy(s) failed.\n`);
+  } else {
+    ctx.err(`\nDeployed ${targets.length} agents.\n`);
+  }
+  return failures === 0 ? 0 : 1;
+}
+
+/**
+ * Resolve which agent directory(ies) to deploy from `--dir` / `--slug` /
+ * `--all`, with an interactive picker when a multi-agent parent is on a TTY.
+ */
+async function resolveDeployTargets(
+  options: DeployCliOptions,
+  ctx: DeployCliContext
+): Promise<DeployTarget[] | number> {
   const dir = resolve(options.dir ?? ".");
-  let slug: string;
+
   if (options.slug !== undefined) {
     const slugError = validateDeploymentSlug(options.slug);
     if (slugError !== undefined) {
       ctx.err(`${slugError}\n`);
       return 1;
     }
-    slug = options.slug;
-  } else {
-    const derived = slugFromDirectoryName(basename(dir));
-    if (derived === undefined) {
+  }
+  if (options.all === true && options.slug !== undefined) {
+    ctx.err("Pass either --slug or --all, not both.\n");
+    return 1;
+  }
+
+  if (await isAgentProjectDir(dir)) {
+    if (options.all === true) {
       ctx.err(
-        `Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.\n`
+        `--all requires a multi-agent parent directory (several child agents under --dir); ${dir} is a single agent project.\n`
       );
       return 1;
     }
-    slug = derived;
-    ctx.err(`Deploying as "${slug}" (from the directory name).\n`);
+    let slug: string;
+    if (options.slug !== undefined) {
+      slug = options.slug;
+    } else {
+      const derived = slugFromDirectoryName(basename(dir));
+      if (derived === undefined) {
+        ctx.err(
+          `Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.\n`
+        );
+        return 1;
+      }
+      slug = derived;
+      if (!ctx.json) {
+        ctx.err(`Deploying as "${slug}" (from the directory name).\n`);
+      }
+    }
+    return [{ slug, dir }];
   }
 
-  if (options.repo !== undefined && !options.repo.startsWith("https://")) {
+  let children: ChildAgentDir[];
+  try {
+    children = await listChildAgentDirs(dir);
+  } catch (error) {
+    ctx.err(`${describeError(error)}\n`);
+    return 1;
+  }
+  // Deploy slugs are lowercase-only; normalize directory names the same way
+  // single-agent deploy does so MixedCase child dirs still deploy.
+  children = children.flatMap((child) => {
+    const slug = slugFromDirectoryName(basename(child.dir));
+    if (slug === undefined) {
+      return [];
+    }
+    return [{ slug, dir: child.dir }];
+  });
+
+  if (children.length === 0) {
+    if (options.all === true) {
+      ctx.err(
+        `--all requires child agent projects under --dir; none found in ${dir}.\n`
+      );
+      return 1;
+    }
+    // Static / bare-slug deploy against a non-agent directory.
+    let slug: string;
+    if (options.slug !== undefined) {
+      slug = options.slug;
+    } else {
+      const derived = slugFromDirectoryName(basename(dir));
+      if (derived === undefined) {
+        ctx.err(
+          `No agent projects under ${dir}, and could not derive a slug from ${JSON.stringify(basename(dir))}; pass --slug or --dir <agent>.\n`
+        );
+        return 1;
+      }
+      slug = derived;
+      if (!ctx.json) {
+        ctx.err(
+          `Deploying as "${slug}" (static; no agent project at ${dir}).\n`
+        );
+      }
+    }
+    return [{ slug, dir }];
+  }
+
+  if (children.length === 1) {
+    const only = children[0]!;
+    if (options.all === true) {
+      // One child is fine for --all (degenerate multi-agent parent).
+    } else if (
+      options.slug !== undefined &&
+      options.slug.toLowerCase() !== only.slug
+    ) {
+      ctx.err(
+        `No agent "${options.slug}" under ${dir}; found "${only.slug}".\n`
+      );
+      return 1;
+    }
+    if (!ctx.json) {
+      ctx.err(
+        `Deploying "${only.slug}" (only agent under ${basename(dir)}).\n`
+      );
+    }
+    return [only];
+  }
+
+  // Multiple children.
+  if (options.all === true) {
+    if (!ctx.json) {
+      ctx.err(
+        `Deploying all ${children.length} agents under ${basename(dir)}: ${children.map((c) => c.slug).join(", ")}.\n`
+      );
+    }
+    return [...children];
+  }
+
+  if (options.slug !== undefined) {
+    const wanted = options.slug.toLowerCase();
+    const match = children.find((child) => child.slug === wanted);
+    if (match === undefined) {
+      ctx.err(
+        `No agent "${options.slug}" under ${dir}.\n` +
+          formatAgentList(children) +
+          `Pass --slug <name> or --all.\n`
+      );
+      return 1;
+    }
+    return [match];
+  }
+
+  const chooser =
+    options.chooseTargets ??
+    ((agents) =>
+      promptChooseDeployTargets(agents, {
+        err: ctx.err,
+        stdin: options.stdin ?? process.stdin,
+        interactive:
+          ctx.json !== true &&
+          (options.stdin ?? process.stdin).isTTY === true &&
+          process.stderr.isTTY === true,
+      }));
+  const chosen = await chooser(children);
+  if (chosen === null) {
+    ctx.err("Deploy cancelled.\n");
+    return 1;
+  }
+  if (chosen.length === 0) {
+    ctx.err(
+      `Multiple agents under ${dir}:\n` +
+        formatAgentList(children) +
+        `Pass --slug <name> or --all (or re-run on a TTY to pick interactively).\n`
+    );
+    return 1;
+  }
+  return chosen;
+}
+
+function formatAgentList(agents: readonly DeployTarget[]): string {
+  return agents.map((agent, i) => `  ${i + 1}) ${agent.slug}\n`).join("");
+}
+
+/**
+ * TTY picker for multi-agent parents. Non-interactive callers get `[]`
+ * so {@link resolveDeployTargets} can print the --slug/--all hint.
+ */
+export async function promptChooseDeployTargets(
+  agents: readonly DeployTarget[],
+  options: {
+    err: (text: string) => void;
+    stdin: SecretInputStream;
+    interactive: boolean;
+  }
+): Promise<DeployTarget[] | null> {
+  options.err(
+    `Multiple agents (${agents.length}):\n` +
+      formatAgentList(agents) +
+      `  a) all\n`
+  );
+  if (!options.interactive) {
+    return [];
+  }
+  options.err('Deploy which? Enter a number, slug, "all", or "q" to cancel: ');
+  const readLine = createLineReader(options.stdin);
+  // createLineReader pauses until data; ensure stdin is flowing on a TTY.
+  options.stdin.resume?.();
+  const answer = (await readLine())?.trim().toLowerCase();
+  if (answer === undefined || answer === "q" || answer === "quit") {
+    return null;
+  }
+  if (answer === "a" || answer === "all" || answer === "*") {
+    return [...agents];
+  }
+  const asIndex = Number.parseInt(answer, 10);
+  if (
+    !Number.isNaN(asIndex) &&
+    String(asIndex) === answer &&
+    asIndex >= 1 &&
+    asIndex <= agents.length
+  ) {
+    return [agents[asIndex - 1]!];
+  }
+  const bySlug = agents.find((agent) => agent.slug.toLowerCase() === answer);
+  if (bySlug !== undefined) {
+    return [bySlug];
+  }
+  options.err(
+    `Unrecognized choice ${JSON.stringify(answer)} — expected 1–${agents.length}, a slug, "all", or "q". Aborting.\n`
+  );
+  return null;
+}
+
+async function deployOne(
+  ctx: DeployCliContext,
+  options: DeployCliOptions,
+  target: DeployTarget,
+  extras?: { jsonCollect?: unknown[] }
+): Promise<number> {
+  const { dir, slug } = target;
+
+  // Fill --repo/--ref/--path from the local git checkout when omitted so
+  // `agentkit deploy` inside an agent directory is enough. Only probe git
+  // for real agent projects (avoids ambient monorepo remotes when someone
+  // deploys a bare --slug). Explicit flags always win.
+  const isAgent = await isAgentProjectDir(dir);
+  const needsGitInference =
+    isAgent &&
+    (options.repo === undefined ||
+      options.ref === undefined ||
+      options.path === undefined);
+  const inferred = needsGitInference
+    ? await inferDeployGitSource(dir, {
+        ...(options.git === undefined ? {} : { git: options.git }),
+      })
+    : {};
+  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
+  const gitRef = options.ref ?? inferred.gitRef;
+  const agentPath = options.path ?? inferred.agentPath;
+
+  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
     ctx.err(
-      `Invalid --repo: ${options.repo} (expected an https:// git repository URL)\n`
+      `Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`
     );
     return 1;
   }
@@ -206,11 +561,31 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     }
   }
 
+  if (!ctx.json && gitRepoUrl !== undefined) {
+    const inferredBits: string[] = [];
+    if (options.repo === undefined && inferred.gitRepoUrl !== undefined) {
+      inferredBits.push("repo");
+    }
+    if (options.ref === undefined && inferred.gitRef !== undefined) {
+      inferredBits.push("ref");
+    }
+    if (options.path === undefined && inferred.agentPath !== undefined) {
+      inferredBits.push("path");
+    }
+    ctx.err(
+      `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
+        (agentPath === undefined ? "" : `  path:   ${agentPath}\n`) +
+        (inferredBits.length === 0
+          ? ""
+          : `  (inferred ${inferredBits.join(", ")} from git; pass --repo/--ref/--path to override)\n`)
+    );
+  }
+
   // The package manifest (`defineAgent({ hosting })`) is the source of
   // truth for egress domains and expected secret names; flags override or
   // augment it. Directories without an agent project (static placeholder
   // deploys) simply have no manifest.
-  const hosting = await readHostingManifest(dir);
+  const hosting = isAgent ? await readHostingManifest(dir) : undefined;
   const egressAllowedDomains = [
     ...new Set([
       ...(hosting?.egressDomains ?? []),
@@ -222,9 +597,9 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
   // serves the static placeholder). See DeploySource for the artifact seam.
   const source: DeploySource = {
     kind: "git-ref",
-    ...(options.repo === undefined ? {} : { gitRepoUrl: options.repo }),
-    ...(options.ref === undefined ? {} : { gitRef: options.ref }),
-    ...(options.path === undefined ? {} : { agentPath: options.path }),
+    ...(gitRepoUrl === undefined ? {} : { gitRepoUrl }),
+    ...(gitRef === undefined ? {} : { gitRef }),
+    ...(agentPath === undefined ? {} : { agentPath }),
     ...(options.cursorEventsRepos === undefined ||
     options.cursorEventsRepos.length === 0
       ? {}
@@ -245,7 +620,9 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
   }
 
   if (ctx.noWait) {
-    if (ctx.json) {
+    if (extras?.jsonCollect !== undefined) {
+      extras.jsonCollect.push(accepted);
+    } else if (ctx.json) {
       ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
     } else {
       ctx.out(
@@ -266,16 +643,18 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
 
   warnMissingSecrets(ctx, slug, hosting?.secretNames, detail.secretNames);
 
+  const payload =
+    accepted.aliasToken === undefined
+      ? detail
+      : { ...detail, aliasToken: accepted.aliasToken };
+
+  if (extras?.jsonCollect !== undefined) {
+    extras.jsonCollect.push(payload);
+    return detail.status === "running" ? 0 : 1;
+  }
+
   if (ctx.json) {
-    ctx.out(
-      `${JSON.stringify(
-        accepted.aliasToken === undefined
-          ? detail
-          : { ...detail, aliasToken: accepted.aliasToken },
-        null,
-        2
-      )}\n`
-    );
+    ctx.out(`${JSON.stringify(payload, null, 2)}\n`);
     return detail.status === "running" ? 0 : 1;
   }
 
@@ -295,7 +674,7 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
       `  generation:  ${detail.generation}\n` +
       `  kind:        ${detail.deploymentKind}\n` +
       `  alias:       ${aliasUrl}\n` +
-      `  playground:  ${aliasUrl}/playground (send X-Agent-Alias-Token)\n`
+      `  playground:  ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
   );
   return 0;
 }

package/src/internal/cursor/credentials.ts

@@ -23,6 +23,7 @@ import { z } from "zod";
 import { CLI_COMMAND_NAME } from "../distribution.js";
 
 export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
+export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
 
 /** Backend API base URL (`CURSOR_API_BASE_URL` override for local dev). */
@@ -32,6 +33,19 @@ export function cursorBackendUrl(): string {
   );
 }
 
+/**
+ * External API base URL for routes served only by the external-api
+ * microlith (`/internal/agent-serve/*`, engine aliases). In production
+ * these are mounted on api.cursor.com and 404 on api2.cursor.sh, so the
+ * deploy surface needs its own default. `CURSOR_API_BASE_URL` still
+ * overrides everything for local dev, where one server mounts all routes.
+ */
+export function cursorExternalApiUrl(): string {
+  return trimTrailingSlash(
+    process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_EXTERNAL_API_URL
+  );
+}
+
 /** Website base URL for the login deep link (`CURSOR_WEBSITE_URL` override). */
 export function cursorWebsiteUrl(): string {
   return trimTrailingSlash(