@cursor/july 0.1.1 → 0.1.3

package/src/internal/deploy-client.ts

@@ -0,0 +1,632 @@
+/**
+ * Thin client for the Agent Serve deployment management API
+ * (`/internal/agent-serve/deployments` on the Cursor backend). Pure
+ * request/response + error mapping — no console I/O, no polling loops;
+ * rendering lives in `cli-deploy.ts`.
+ *
+ * Auth is the user API key sent directly as the bearer (the routes are
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
+ * The endpoints are gated on the `agent_serve_mvp` Statsig gate and 404
+ * when it is off — the error mapping says so instead of "not found".
+ */
+
+import { z } from "zod";
+import {
+  MAX_SECRET_VALUE_BYTES,
+  MAX_SECRETS,
+  validateEgressDomain,
+  validateSettableSecretName,
+} from "./hosting.js";
+
+export type DeploymentStatus =
+  | "pending"
+  | "deploying"
+  | "running"
+  | "degraded"
+  | "failed"
+  | "stopping"
+  | "stopped";
+
+/** Customer-safe deploy progress (no hosting phase / infra names). */
+export type DeploymentProgress =
+  | "queued"
+  | "preparing"
+  | "building"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "degraded";
+
+export const TERMINAL_DEPLOY_STATUSES: ReadonlySet<DeploymentStatus> = new Set([
+  "running",
+  "degraded",
+  "failed",
+  "stopped",
+]);
+
+/**
+ * What gets deployed. Today the control plane builds the engine itself from
+ * a git ref (or serves the static placeholder when no repo is given), so the
+ * only member is the slug/git-ref shape. When artifact-based deploys ship
+ * ("build locally + upload"), add an `{ kind: "artifact", ... }` member here
+ * and a branch in {@link AgentServeDeployClient.deploy} — the command
+ * surface and everything downstream stays unchanged.
+ */
+export type DeploySource = {
+  kind: "git-ref";
+  /** Omit for the control-plane static engine (`static-http-200`). */
+  gitRepoUrl?: string;
+  gitRef?: string;
+  agentPath?: string;
+  /** Repos whose SCM events the deployed engine pulls (`owner/name`). */
+  cursorEventRepos?: string[];
+  /**
+   * Egress allowlist for the engine pod. Only valid on repo-backed
+   * deploys — the backend 400s when set on a static deploy.
+   */
+  egressAllowedDomains?: string[];
+};
+
+const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
+
+/** Returns a human error message, or undefined when the slug is valid. */
+export function validateDeploymentSlug(slug: string): string | undefined {
+  if (SLUG_PATTERN.test(slug)) {
+    return undefined;
+  }
+  return `Invalid slug ${JSON.stringify(slug)}: use lowercase letters, digits, '-' or '_' (max 64 chars)`;
+}
+
+/** Derive a valid slug from a directory name, or undefined if impossible. */
+export function slugFromDirectoryName(name: string): string | undefined {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return SLUG_PATTERN.test(slug) ? slug : undefined;
+}
+
+export class DeployApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    /** Seconds to wait before retrying (from `Retry-After` on 429s). */
+    readonly retryAfterSeconds?: number
+  ) {
+    super(message);
+    this.name = "DeployApiError";
+  }
+}
+
+// ============================================================================
+// Response shapes (backend `serializeDeployment` + route-specific bodies).
+// Interfaces are hand-written (the package compiles with
+// --isolatedDeclarations, so exported types cannot be z.infer of an
+// unannotated schema); the zod schemas below stay module-internal.
+// ============================================================================
+
+export interface DeployAccepted {
+  id: number;
+  slug: string;
+  teamId: number;
+  status: string;
+  generation: number;
+  deploymentKind: string;
+  engineAlias: string;
+  /** Present exactly once, on the deploy that minted the record. */
+  aliasToken?: string;
+}
+
+export interface Deployment {
+  id: number;
+  slug: string;
+  teamId: number;
+  deploymentKind: string;
+  gitRepoUrl?: string | null;
+  gitRef?: string;
+  agentPath?: string;
+  desiredState?: string;
+  status: DeploymentStatus;
+  /**
+   * Customer-safe deploy progress (no hosting internals). Present on newer
+   * backends; older responses omit it.
+   */
+  progress?: DeploymentProgress;
+  generation: number;
+  observedGeneration?: number | null;
+  engineGeneration?: number | null;
+  publicId?: string;
+  engineUrl?: string | null;
+  lastError?: string | null;
+  engineAlias: string;
+  desiredUpdatedAt?: string;
+  lastReconciledAt?: string | null;
+  /** SCM-event repos configured on the deployment (`owner/name`). */
+  cursorEventRepos?: string[];
+  /** Normalized egress allowlist for the engine pod. */
+  egressAllowedDomains?: string[];
+  /** Service-account id (`sa_…`); null on legacy rows. */
+  serviceAccountId?: string | number | null;
+  /** Masked pod credential; the raw key is never returned. */
+  podCredentialMaskedKey?: string | null;
+  /** Names of the secrets set on the deployment (values never returned). */
+  secretNames?: string[];
+}
+
+/** Short-lived direct pod access minted by the status route. */
+export interface EngineAccess {
+  url: string;
+  headers: Record<string, string>;
+  expiresAt: string;
+}
+
+export interface DeploymentDetail extends Deployment {
+  engineAccess?: EngineAccess | null;
+}
+
+export interface StopAccepted {
+  id: number;
+  status: string;
+}
+
+/** One secret's metadata from the list endpoint — names only, never values. */
+export interface SecretInfo {
+  name: string;
+  createdAt: string;
+}
+
+// All response schemas are `.passthrough()`: the backend keeps growing the
+// deployment payload (serviceAccountId, egressAllowedDomains, secret
+// metadata, ...) and unknown fields must flow through untouched — both so
+// parsing never breaks on a newer backend and so `--json` output stays
+// faithful to the API instead of silently dropping fields.
+const deployAcceptedSchema = z
+  .object({
+    id: z.number(),
+    slug: z.string(),
+    teamId: z.number(),
+    status: z.string(),
+    generation: z.number(),
+    deploymentKind: z.string(),
+    engineAlias: z.string(),
+    aliasToken: z.string().optional(),
+  })
+  .passthrough();
+
+const deploymentSchema = z.object({
+  id: z.number(),
+  slug: z.string(),
+  teamId: z.number(),
+  deploymentKind: z.string(),
+  gitRepoUrl: z.string().nullable().optional(),
+  gitRef: z.string().optional(),
+  agentPath: z.string().optional(),
+  desiredState: z.string().optional(),
+  status: z.enum([
+    "pending",
+    "deploying",
+    "running",
+    "degraded",
+    "failed",
+    "stopping",
+    "stopped",
+  ]),
+  progress: z
+    .enum([
+      "queued",
+      "preparing",
+      "building",
+      "finalizing",
+      "running",
+      "failed",
+      "stopping",
+      "stopped",
+      "degraded",
+    ])
+    .optional(),
+  generation: z.number(),
+  observedGeneration: z.number().nullable().optional(),
+  engineGeneration: z.number().nullable().optional(),
+  publicId: z.string().optional(),
+  engineUrl: z.string().nullable().optional(),
+  lastError: z.string().nullable().optional(),
+  engineAlias: z.string(),
+  desiredUpdatedAt: z.string().optional(),
+  lastReconciledAt: z.string().nullable().optional(),
+  cursorEventRepos: z.array(z.string()).optional(),
+  egressAllowedDomains: z.array(z.string()).optional(),
+  // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
+  // legacy rows that predate service-account-backed deploys.
+  serviceAccountId: z.union([z.string(), z.number()]).nullable().optional(),
+  podCredentialMaskedKey: z.string().nullable().optional(),
+  secretNames: z.array(z.string()).optional(),
+});
+
+const deploymentListItemSchema = deploymentSchema.passthrough();
+
+const deploymentDetailSchema = deploymentSchema
+  .extend({
+    engineAccess: z
+      .object({
+        url: z.string(),
+        headers: z.record(z.string()),
+        expiresAt: z.string(),
+      })
+      .nullable()
+      .optional(),
+  })
+  .passthrough();
+
+const listResponseSchema = z.object({
+  deployments: z.array(deploymentListItemSchema),
+});
+
+const stopAcceptedSchema = z
+  .object({
+    id: z.number(),
+    status: z.string(),
+  })
+  .passthrough();
+
+const rotateResponseSchema = z
+  .object({
+    aliasToken: z.string().min(1),
+  })
+  .passthrough();
+
+const rotatePodCredentialResponseSchema = z
+  .object({
+    podCredentialMaskedKey: z.string().min(1),
+  })
+  .passthrough();
+
+const setSecretsResponseSchema = z
+  .object({
+    secretNames: z.array(z.string()),
+  })
+  .passthrough();
+
+const listSecretsResponseSchema = z
+  .object({
+    secrets: z.array(
+      z.object({ name: z.string(), createdAt: z.string() }).passthrough()
+    ),
+  })
+  .passthrough();
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface AgentServeDeployClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class AgentServeDeployClient {
+  private readonly backendUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: AgentServeDeployClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /** Create or redeploy; 202 means accepted, not running (poll status). */
+  async deploy(args: {
+    teamId: number;
+    slug: string;
+    source: DeploySource;
+  }): Promise<DeployAccepted> {
+    const slugError = validateDeploymentSlug(args.slug);
+    if (slugError !== undefined) {
+      throw new DeployApiError(slugError, 400);
+    }
+    for (const domain of args.source.egressAllowedDomains ?? []) {
+      const domainError = validateEgressDomain(domain);
+      if (domainError !== undefined) {
+        throw new DeployApiError(domainError, 400);
+      }
+    }
+    // Only the git-ref member exists today; a future artifact member would
+    // upload the build first and post a different body from this branch.
+    const body: Record<string, unknown> = {
+      teamId: args.teamId,
+      slug: args.slug,
+      ...(args.source.gitRepoUrl === undefined
+        ? {}
+        : { gitRepoUrl: args.source.gitRepoUrl }),
+      ...(args.source.gitRef === undefined
+        ? {}
+        : { gitRef: args.source.gitRef }),
+      ...(args.source.agentPath === undefined
+        ? {}
+        : { agentPath: args.source.agentPath }),
+      ...(args.source.cursorEventRepos === undefined
+        ? {}
+        : { cursorEventRepos: args.source.cursorEventRepos }),
+      ...(args.source.egressAllowedDomains === undefined
+        ? {}
+        : { egressAllowedDomains: args.source.egressAllowedDomains }),
+    };
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agent-serve/deployments",
+      body,
+      context: { verb: "deploy", slug: args.slug },
+    });
+    return deployAcceptedSchema.parse(raw);
+  }
+
+  async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments?teamId=${args.teamId}`,
+      context: { verb: "list deployments" },
+    });
+    return listResponseSchema.parse(raw).deployments;
+  }
+
+  async getDeployment(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<DeploymentDetail> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "get deployment", slug: args.slug },
+    });
+    return deploymentDetailSchema.parse(raw);
+  }
+
+  async stopDeployment(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<StopAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/stop?teamId=${args.teamId}`,
+      context: { verb: "stop", slug: args.slug },
+    });
+    return stopAcceptedSchema.parse(raw);
+  }
+
+  /** Returns the new alias token exactly once; the old one dies now. */
+  async rotateAliasToken(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/rotate-alias-token?teamId=${args.teamId}`,
+      context: { verb: "rotate alias token", slug: args.slug },
+    });
+    return rotateResponseSchema.parse(raw).aliasToken;
+  }
+
+  /**
+   * Upsert secrets by name (unlisted names stay untouched). Returns the
+   * post-write union of secret names, sorted. Validates names and value
+   * sizes client-side with the backend's grammar before any network call.
+   */
+  async setSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]> {
+    for (const { name, value } of args.secrets) {
+      const nameError = validateSettableSecretName(name);
+      if (nameError !== undefined) {
+        throw new DeployApiError(nameError, 400);
+      }
+      if (Buffer.byteLength(value, "utf8") > MAX_SECRET_VALUE_BYTES) {
+        throw new DeployApiError(
+          `The value for ${name} is too large (max ${MAX_SECRET_VALUE_BYTES} bytes).`,
+          400
+        );
+      }
+    }
+    if (args.secrets.length > MAX_SECRETS) {
+      throw new DeployApiError(
+        `Too many secrets in one request (${args.secrets.length}); deployments hold at most ${MAX_SECRETS}.`,
+        400
+      );
+    }
+    const raw = await this.request({
+      method: "PUT",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets`,
+      body: { teamId: args.teamId, secrets: args.secrets },
+      context: { verb: "set secrets", slug: args.slug },
+    });
+    return setSecretsResponseSchema.parse(raw).secretNames;
+  }
+
+  /** Secret names + creation times; values are never returned. */
+  async listSecrets(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<SecretInfo[]> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets?teamId=${args.teamId}`,
+      context: { verb: "list secrets", slug: args.slug },
+    });
+    return listSecretsResponseSchema.parse(raw).secrets;
+  }
+
+  /** Remove one secret by name; 404 when it is not set. */
+  async deleteSecret(args: {
+    teamId: number;
+    slug: string;
+    name: string;
+  }): Promise<void> {
+    const nameError = validateSettableSecretName(args.name);
+    if (nameError !== undefined) {
+      throw new DeployApiError(nameError, 400);
+    }
+    await this.request({
+      method: "DELETE",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/secrets/${encodeURIComponent(args.name)}?teamId=${args.teamId}`,
+      context: { verb: "unset secret", slug: args.slug },
+    });
+  }
+
+  /**
+   * Rotate the deployment's pod credential. Returns the masked new key —
+   * the raw key is injected into the pod on the next deploy, never
+   * returned to clients.
+   */
+  async rotatePodCredential(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/deployments/${encodeURIComponent(args.slug)}/rotate-pod-credential?teamId=${args.teamId}`,
+      context: { verb: "rotate pod credential", slug: args.slug },
+    });
+    return rotatePodCredentialResponseSchema.parse(raw).podCredentialMaskedKey;
+  }
+
+  /** Full URL of the stable engine alias for a deployment. */
+  aliasUrl(engineAlias: string): string {
+    return `${this.backendUrl}${engineAlias}`;
+  }
+
+  private async request(args: {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+    context: { verb: string; slug?: string };
+  }): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}${args.path}`, {
+        method: args.method,
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+          ...(args.body === undefined
+            ? {}
+            : { "content-type": "application/json" }),
+        },
+        ...(args.body === undefined ? {} : { body: JSON.stringify(args.body) }),
+        signal: AbortSignal.timeout(60_000),
+      });
+    } catch (error) {
+      throw new DeployApiError(
+        `Could not reach the Cursor backend at ${this.backendUrl}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        0
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw mapErrorResponse(response, text, args.context);
+    }
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new DeployApiError(
+        `The Cursor backend returned a non-JSON response to ${args.context.verb}.`,
+        response.status
+      );
+    }
+  }
+}
+
+// ============================================================================
+// Error mapping (HTTP → actionable human messages)
+// ============================================================================
+
+function serverErrorText(bodyText: string): string | undefined {
+  try {
+    const parsed = JSON.parse(bodyText) as { error?: unknown };
+    if (typeof parsed.error === "string" && parsed.error !== "") {
+      return parsed.error;
+    }
+  } catch {
+    // Non-JSON body — fall through.
+  }
+  return undefined;
+}
+
+function mapErrorResponse(
+  response: Response,
+  bodyText: string,
+  context: { verb: string; slug?: string }
+): DeployApiError {
+  const serverError = serverErrorText(bodyText);
+  const slugPart = context.slug === undefined ? "" : ` "${context.slug}"`;
+  switch (response.status) {
+    case 400:
+      return new DeployApiError(
+        serverError ?? `The ${context.verb} request was rejected as invalid.`,
+        400
+      );
+    case 401:
+      return new DeployApiError(
+        "The Cursor API key was rejected. Run `agentkit login` again or update CURSOR_API_KEY.",
+        401
+      );
+    case 403:
+      return new DeployApiError(
+        `${serverError ?? "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`,
+        403
+      );
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a missing deployment / closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new DeployApiError(
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          404
+        );
+      }
+      return new DeployApiError(
+        context.slug === undefined
+          ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`
+          : `Deployment${slugPart} was not found — check the slug and --team, or the agent_serve_mvp feature gate may not be enabled for your team.`,
+        404
+      );
+    }
+    case 409:
+      return new DeployApiError(
+        `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,
+        409
+      );
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSeconds =
+        retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
+          ? Number(retryAfterHeader)
+          : undefined;
+      return new DeployApiError(
+        `${serverError ?? "Rate limited"}${
+          retryAfterSeconds === undefined
+            ? ""
+            : ` — retry in ${retryAfterSeconds}s`
+        }`,
+        429,
+        retryAfterSeconds
+      );
+    }
+    default:
+      return new DeployApiError(
+        `The ${context.verb} request failed (${response.status}): ${
+          serverError ?? bodyText.slice(0, 300) ?? "(empty body)"
+        }`,
+        response.status
+      );
+  }
+}