@cursor/july 0.1.1 → 0.1.3

package/src/internal/cli-deploy.ts

@@ -0,0 +1,1319 @@
+/**
+ * `agentkit deploy | deployments | deployment | stop | rotate-token |
+ * rotate-pod-credential | secrets set|list|unset` — Heroku-style deploys
+ * onto Cursor's managed agent-serve hosting.
+ *
+ * All intelligence is server-side (backend/server/src/agentServe/); these
+ * handlers resolve parameters (credentials, team, slug, the project's
+ * `hosting` manifest block), call the management API through
+ * `deploy-client.ts`, poll status, and render.
+ */
+
+import { basename, resolve } from "node:path";
+import type { AgentHostingOptions } from "../types.js";
+import { CursorBackendClient } from "./cursor/backend-client.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKey,
+  SIGN_IN_HINT,
+} from "./cursor/credentials.js";
+import {
+  AgentServeDeployClient,
+  type DeployAccepted,
+  DeployApiError,
+  type Deployment,
+  type DeploymentDetail,
+  type DeploymentStatus,
+  type DeploySource,
+  type SecretInfo,
+  type StopAccepted,
+  slugFromDirectoryName,
+  TERMINAL_DEPLOY_STATUSES,
+  validateDeploymentSlug,
+} from "./deploy-client.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.
+   * Optional — inferred from `git remote origin` when omitted inside an
+   * agent project checkout.
+   */
+  repo?: string;
+  /**
+   * 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.
+   * Optional — inferred from `--dir` vs the git toplevel when omitted.
+   */
+  path?: string;
+  /** deploy `--cursor-events-repo <owner/name>` (repeatable). */
+  cursorEventsRepos?: string[];
+  /** deploy `--allow-domain <domain>` (repeatable; unioned with the manifest). */
+  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;
+  err?: (text: string) => void;
+  /** `secrets set` value input (hidden prompt on a TTY, lines otherwise). */
+  stdin?: SecretInputStream;
+}
+
+/** Minimal stdin surface `secrets set` reads values from (test-injectable). */
+export type SecretInputStream = NodeJS.ReadableStream & {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => void;
+};
+
+interface DeployCliContext {
+  client: AgentServeDeployClient;
+  teamId: number;
+  json: boolean;
+  noWait: boolean;
+  pollIntervalMs: number;
+  timeoutMs: number;
+  out: (text: string) => void;
+  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;
+}
+
+/**
+ * Credentials → deploy client → team id. Shared by deploy commands and
+ * `--prod` AX routing. Returns an exit code (error already rendered) on
+ * failure.
+ */
+export async function resolveDeployAuth(
+  options: ResolveDeployAuthOptions
+): Promise<ResolvedDeployAuth | number> {
+  const err =
+    options.err ?? ((text: string) => void process.stderr.write(text));
+
+  const resolved = await resolveApiKey(
+    options.apiKey === undefined ? undefined : { apiKey: options.apiKey }
+  );
+  if (resolved === undefined) {
+    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: cursorExternalApiUrl(),
+    apiKey: resolved.apiKey,
+    fetchImpl: options.fetchImpl,
+  });
+
+  let teamId: number;
+  if (options.team !== undefined) {
+    teamId = Number.parseInt(options.team, 10);
+    if (Number.isNaN(teamId) || teamId <= 0) {
+      err(`Invalid --team: ${options.team} (expected a positive team id)\n`);
+      return 1;
+    }
+  } else {
+    const account = new CursorBackendClient({
+      backendUrl: resolved.backendUrl,
+      apiKey: resolved.apiKey,
+      fetchImpl: options.fetchImpl,
+    });
+    let identity: Awaited<ReturnType<CursorBackendClient["getMe"]>>;
+    try {
+      identity = await account.getMe();
+    } catch (error) {
+      err(
+        `Could not resolve your team from the Cursor account: ${describeError(error)}\nPass --team <id> explicitly.\n`
+      );
+      return 1;
+    }
+    if (identity.teamId === undefined || identity.teamId <= 0) {
+      err(
+        "This Cursor account has no default team; pass --team <id> (find it in the Cursor dashboard URL).\n"
+      );
+      return 1;
+    }
+    teamId = identity.teamId;
+    const dim = stderrPalette().dim;
+    err(
+      `${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: auth.client,
+    teamId: auth.teamId,
+    json: options.json === true,
+    noWait: options.noWait === true,
+    pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs: options.timeoutMs ?? DEFAULT_DEPLOY_TIMEOUT_MS,
+    out,
+    err,
+  };
+}
+
+// ============================================================================
+// deploy
+// ============================================================================
+
+export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
+  const ctx = await prepare(options);
+  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 ?? ".");
+
+  if (options.slug !== undefined) {
+    const slugError = validateDeploymentSlug(options.slug);
+    if (slugError !== undefined) {
+      ctx.err(`${slugError}\n`);
+      return 1;
+    }
+  }
+  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(
+        `--all requires a multi-agent parent directory (several child agents under --dir); ${dir} is a single agent project.\n`
+      );
+      return 1;
+    }
+    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 }];
+  }
+
+  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: ${gitRepoUrl} (expected an https:// git repository URL)\n`
+    );
+    return 1;
+  }
+  for (const repo of options.cursorEventsRepos ?? []) {
+    if (!isValidCursorEventRepo(repo)) {
+      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
+      return 1;
+    }
+  }
+
+  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 = isAgent ? await readHostingManifest(dir) : undefined;
+  const egressAllowedDomains = [
+    ...new Set([
+      ...(hosting?.egressDomains ?? []),
+      ...(options.allowDomains ?? []),
+    ]),
+  ];
+
+  // Today's only source shape: the control plane builds from a git ref (or
+  // serves the static placeholder). See DeploySource for the artifact seam.
+  const source: DeploySource = {
+    kind: "git-ref",
+    ...(gitRepoUrl === undefined ? {} : { gitRepoUrl }),
+    ...(gitRef === undefined ? {} : { gitRef }),
+    ...(agentPath === undefined ? {} : { agentPath }),
+    ...(options.cursorEventsRepos === undefined ||
+    options.cursorEventsRepos.length === 0
+      ? {}
+      : { cursorEventRepos: options.cursorEventsRepos }),
+    ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
+  };
+
+  let accepted: DeployAccepted;
+  try {
+    accepted = await ctx.client.deploy({ teamId: ctx.teamId, slug, source });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+
+  const aliasUrl = ctx.client.aliasUrl(accepted.engineAlias);
+  if (!ctx.json && accepted.aliasToken !== undefined) {
+    ctx.out(aliasTokenBlock(accepted.aliasToken));
+  }
+
+  if (ctx.noWait) {
+    if (extras?.jsonCollect !== undefined) {
+      extras.jsonCollect.push(accepted);
+    } else if (ctx.json) {
+      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
+    } else {
+      ctx.out(
+        `Deploy accepted: ${slug} (team ${ctx.teamId}, generation ${accepted.generation}, ${accepted.deploymentKind})\n` +
+          `  alias: ${aliasUrl}\n` +
+          `Check progress with \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.\n`
+      );
+    }
+    return 0;
+  }
+
+  let detail: DeploymentDetail;
+  try {
+    detail = await pollUntil(ctx, slug, TERMINAL_DEPLOY_STATUSES);
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+
+  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(payload, null, 2)}\n`);
+    return detail.status === "running" ? 0 : 1;
+  }
+
+  if (detail.status !== "running") {
+    ctx.err(
+      `Deployment ${slug} ended ${detail.status}${
+        detail.lastError === null || detail.lastError === undefined
+          ? ""
+          : `: ${detail.lastError}`
+      }\n`
+    );
+    return 1;
+  }
+  ctx.out(
+    `Deployed ${slug} (team ${ctx.teamId})\n` +
+      `  status:      running\n` +
+      `  generation:  ${detail.generation}\n` +
+      `  kind:        ${detail.deploymentKind}\n` +
+      `  alias:       ${aliasUrl}\n` +
+      `  playground:  ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
+  );
+  return 0;
+}
+
+/**
+ * Read the `hosting` block from the project manifest at `dir`, or
+ * undefined when the directory is not an agent project (static deploys
+ * have nothing to discover).
+ */
+async function readHostingManifest(
+  dir: string
+): Promise<AgentHostingOptions | undefined> {
+  if (!(await isAgentProjectDir(dir))) {
+    return undefined;
+  }
+  const project = await loadAgentProject(dir);
+  return project.agent.hosting;
+}
+
+/**
+ * Friendly post-deploy nudge: the manifest declares secrets the agent
+ * expects, but the deployment does not have them all set yet.
+ */
+function warnMissingSecrets(
+  ctx: DeployCliContext,
+  slug: string,
+  declared: string[] | undefined,
+  set: string[] | undefined
+): void {
+  if (declared === undefined || declared.length === 0) {
+    return;
+  }
+  const setNames = new Set(set ?? []);
+  const missing = declared.filter((name) => !setNames.has(name));
+  if (missing.length === 0) {
+    return;
+  }
+  ctx.err(
+    `warning: secrets declared in the agent manifest but not set on ${slug}: ${missing.join(", ")}\n` +
+      `  set them with \`${CLI} secrets set ${slug} ${missing.join(" ")}\`\n`
+  );
+}
+
+// ============================================================================
+// deployments (list)
+// ============================================================================
+
+export async function cmdDeployments(
+  options: DeployCliOptions
+): Promise<number> {
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let deployments: Deployment[];
+  try {
+    deployments = await ctx.client.listDeployments({ teamId: ctx.teamId });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ deployments }, null, 2)}\n`);
+    return 0;
+  }
+  if (deployments.length === 0) {
+    ctx.out(
+      `No deployments on team ${ctx.teamId}. Create one with \`${CLI} deploy\`.\n`
+    );
+    return 0;
+  }
+  ctx.out(
+    `${renderTable(
+      ["SLUG", "STATUS", "GEN", "KIND", "UPDATED"],
+      deployments.map((d) => [
+        d.slug,
+        d.status,
+        String(d.generation),
+        d.deploymentKind,
+        d.desiredUpdatedAt ?? "",
+      ])
+    )}\n`
+  );
+  return 0;
+}
+
+// ============================================================================
+// deployment <slug> (detail)
+// ============================================================================
+
+export async function cmdDeploymentStatus(
+  slug: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} deployment <slug> [--team <id>] [--json]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let detail: DeploymentDetail;
+  try {
+    detail = await ctx.client.getDeployment({ teamId: ctx.teamId, slug });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+    return 0;
+  }
+  const aliasUrl = ctx.client.aliasUrl(detail.engineAlias);
+  const lines = [
+    `${detail.slug} (team ${detail.teamId})`,
+    `  status:      ${detail.status}`,
+    `  generation:  ${detail.generation}`,
+    `  kind:        ${detail.deploymentKind}`,
+    `  alias:       ${aliasUrl}`,
+  ];
+  if (detail.gitRepoUrl !== null && detail.gitRepoUrl !== undefined) {
+    lines.push(`  repo:        ${detail.gitRepoUrl} @ ${detail.gitRef ?? ""}`);
+  }
+  if (
+    detail.serviceAccountId !== undefined &&
+    detail.serviceAccountId !== null
+  ) {
+    lines.push(`  service account: ${detail.serviceAccountId}`);
+  }
+  if (
+    detail.egressAllowedDomains !== undefined &&
+    detail.egressAllowedDomains.length > 0
+  ) {
+    lines.push(`  egress:      ${detail.egressAllowedDomains.join(", ")}`);
+  }
+  if (detail.secretNames !== undefined && detail.secretNames.length > 0) {
+    lines.push(`  secrets:     ${detail.secretNames.join(", ")}`);
+  }
+  if (
+    detail.podCredentialMaskedKey !== undefined &&
+    detail.podCredentialMaskedKey !== null
+  ) {
+    lines.push(`  pod credential: ${detail.podCredentialMaskedKey}`);
+  }
+  if (detail.engineUrl !== null && detail.engineUrl !== undefined) {
+    lines.push(`  engine:      ${detail.engineUrl}`);
+  }
+  if (
+    detail.engineAccess !== null &&
+    detail.engineAccess !== undefined &&
+    typeof detail.engineAccess === "object"
+  ) {
+    lines.push(
+      `  engine access: ${detail.engineAccess.url} (expires ${detail.engineAccess.expiresAt})`
+    );
+  }
+  if (detail.lastError !== null && detail.lastError !== undefined) {
+    lines.push(`  last error:  ${detail.lastError}`);
+  }
+  if (detail.desiredUpdatedAt !== undefined) {
+    lines.push(`  updated:     ${detail.desiredUpdatedAt}`);
+  }
+  ctx.out(`${lines.join("\n")}\n`);
+  return 0;
+}
+
+// ============================================================================
+// stop <slug>
+// ============================================================================
+
+export async function cmdStop(
+  slug: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} stop <slug> [--team <id>] [--json] [--no-wait]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let accepted: StopAccepted;
+  try {
+    accepted = await ctx.client.stopDeployment({ teamId: ctx.teamId, slug });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.noWait) {
+    if (ctx.json) {
+      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
+    } else {
+      ctx.out(`Stop accepted for ${slug} (status: ${accepted.status}).\n`);
+    }
+    return 0;
+  }
+  let detail: DeploymentDetail;
+  try {
+    detail = await pollUntil(ctx, slug, new Set(["stopped"]));
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+  } else {
+    ctx.out(`Stopped ${slug} (team ${ctx.teamId}).\n`);
+  }
+  return 0;
+}
+
+// ============================================================================
+// rotate-token <slug>
+// ============================================================================
+
+export async function cmdRotateToken(
+  slug: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} rotate-token <slug> [--team <id>]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let aliasToken: string;
+  try {
+    aliasToken = await ctx.client.rotateAliasToken({
+      teamId: ctx.teamId,
+      slug,
+    });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ aliasToken }, null, 2)}\n`);
+    return 0;
+  }
+  ctx.out(
+    `Rotated the alias token for ${slug}. The old token stopped working immediately.\n${aliasTokenBlock(aliasToken)}`
+  );
+  return 0;
+}
+
+// ============================================================================
+// rotate-pod-credential <slug>
+// ============================================================================
+
+export async function cmdRotatePodCredential(
+  slug: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} rotate-pod-credential <slug> [--team <id>]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let podCredentialMaskedKey: string;
+  try {
+    podCredentialMaskedKey = await ctx.client.rotatePodCredential({
+      teamId: ctx.teamId,
+      slug,
+    });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ podCredentialMaskedKey }, null, 2)}\n`);
+    return 0;
+  }
+  ctx.out(
+    `Rotated the pod credential for ${slug}: ${podCredentialMaskedKey}\n` +
+      `The running pod keeps the old credential until the next deploy — run \`${CLI} deploy --slug ${slug}\` to apply it.\n`
+  );
+  return 0;
+}
+
+// ============================================================================
+// secrets set|list|unset
+// ============================================================================
+
+export async function cmdSecretsSet(
+  slug: string | undefined,
+  specs: string[],
+  options: DeployCliOptions
+): Promise<number> {
+  const usageErr = options.err ?? ((t: string) => void process.stderr.write(t));
+  if (slug === undefined || slug === "" || specs.length === 0) {
+    usageErr(
+      `Usage: ${CLI} secrets set <slug> NAME[=VALUE] [NAME2[=VALUE2] ...] [--team <id>] [--json]\n` +
+        `NAMEs without =VALUE are prompted for (hidden input; reads stdin when piped).\n`
+    );
+    return 1;
+  }
+
+  // Parse and validate every name before prompting for any value, so a
+  // typo in the last name cannot waste typed-in secrets.
+  const parsed: Array<{ name: string; value?: string }> = [];
+  for (const spec of specs) {
+    const eq = spec.indexOf("=");
+    const name = eq === -1 ? spec : spec.slice(0, eq);
+    const nameError = validateSettableSecretName(name);
+    if (nameError !== undefined) {
+      usageErr(`${nameError}\n`);
+      return 1;
+    }
+    parsed.push(eq === -1 ? { name } : { name, value: spec.slice(eq + 1) });
+  }
+  if (parsed.some((entry) => entry.value !== undefined)) {
+    usageErr(
+      `warning: secret values passed as arguments can end up in shell history; prefer \`${CLI} secrets set ${slug} NAME\` and enter the value at the hidden prompt.\n`
+    );
+  }
+
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+
+  const stdin = options.stdin ?? process.stdin;
+  const readValue = createSecretValueReader(stdin, ctx.err);
+  const secrets: Array<{ name: string; value: string }> = [];
+  for (const entry of parsed) {
+    secrets.push({
+      name: entry.name,
+      value: entry.value ?? (await readValue(entry.name)),
+    });
+  }
+
+  let secretNames: string[];
+  try {
+    secretNames = await ctx.client.setSecrets({
+      teamId: ctx.teamId,
+      slug,
+      secrets,
+    });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ secretNames }, null, 2)}\n`);
+    return 0;
+  }
+  ctx.out(
+    `Set ${secrets.length} secret${secrets.length === 1 ? "" : "s"} on ${slug}.\n` +
+      `Secrets now set: ${secretNames.join(", ")}\n` +
+      `The engine picks them up on its next deploy.\n`
+  );
+  return 0;
+}
+
+export async function cmdSecretsList(
+  slug: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} secrets list <slug> [--team <id>] [--json]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  let secrets: SecretInfo[];
+  try {
+    secrets = await ctx.client.listSecrets({ teamId: ctx.teamId, slug });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ secrets }, null, 2)}\n`);
+    return 0;
+  }
+  if (secrets.length === 0) {
+    ctx.out(
+      `No secrets set on ${slug}. Add one with \`${CLI} secrets set ${slug} NAME\`.\n`
+    );
+    return 0;
+  }
+  ctx.out(
+    `${renderTable(
+      ["NAME", "CREATED"],
+      secrets.map((secret) => [secret.name, secret.createdAt])
+    )}\n`
+  );
+  return 0;
+}
+
+export async function cmdSecretsUnset(
+  slug: string | undefined,
+  name: string | undefined,
+  options: DeployCliOptions
+): Promise<number> {
+  if (slug === undefined || slug === "" || name === undefined || name === "") {
+    (options.err ?? ((t: string) => void process.stderr.write(t)))(
+      `Usage: ${CLI} secrets unset <slug> NAME [--team <id>]\n`
+    );
+    return 1;
+  }
+  const ctx = await prepare(options);
+  if (typeof ctx === "number") {
+    return ctx;
+  }
+  try {
+    await ctx.client.deleteSecret({ teamId: ctx.teamId, slug, name });
+  } catch (error) {
+    if (error instanceof DeployApiError && error.status === 404) {
+      ctx.err(
+        `No secret named ${name} on deployment ${slug} — check \`${CLI} secrets list ${slug}\` (and the slug / --team).\n`
+      );
+      return 1;
+    }
+    return renderApiError(error, ctx.err);
+  }
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify({ removed: name }, null, 2)}\n`);
+  } else {
+    ctx.out(`Removed secret ${name} from ${slug}.\n`);
+  }
+  return 0;
+}
+
+/**
+ * Returns a reader for interactive secret values: hidden (no-echo) prompt
+ * when `stdin` is a TTY, otherwise one line per secret from the piped
+ * stream. One reader per command so piped lines are consumed in order.
+ */
+function createSecretValueReader(
+  stdin: SecretInputStream,
+  err: (text: string) => void
+): (name: string) => Promise<string> {
+  if (stdin.isTTY === true) {
+    return (name) => promptHidden(stdin, err, `Value for ${name}: `);
+  }
+  const readLine = createLineReader(stdin);
+  return async (name) => {
+    const line = await readLine();
+    if (line === undefined) {
+      throw new DeployApiError(
+        `stdin ended before a value for ${name} was provided (pipe one line per secret).`,
+        0
+      );
+    }
+    return line;
+  };
+}
+
+/** Raw-mode hidden prompt: echoes nothing, supports backspace and Ctrl-C. */
+function promptHidden(
+  stdin: SecretInputStream,
+  err: (text: string) => void,
+  prompt: string
+): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    err(prompt);
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    let value = "";
+    const cleanup = (): void => {
+      stdin.off("data", onData);
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      err("\n");
+    };
+    const onData = (chunk: Buffer | string): void => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      for (const ch of text) {
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          resolvePromise(value);
+          return;
+        }
+        if (ch === "\u0003") {
+          cleanup();
+          reject(new DeployApiError("Aborted.", 0));
+          return;
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+/** Buffered line reader over a piped stream; undefined once it ends. */
+function createLineReader(
+  stream: NodeJS.ReadableStream
+): () => Promise<string | undefined> {
+  let buffer = "";
+  let ended = false;
+  const waiters: Array<(line: string | undefined) => void> = [];
+
+  const drain = (): void => {
+    while (waiters.length > 0) {
+      const newline = buffer.indexOf("\n");
+      if (newline !== -1) {
+        const line = buffer.slice(0, newline).replace(/\r$/, "");
+        buffer = buffer.slice(newline + 1);
+        waiters.shift()?.(line);
+        continue;
+      }
+      if (!ended) {
+        return;
+      }
+      // Stream ended: a trailing unterminated line still counts once.
+      const rest = buffer;
+      buffer = "";
+      waiters.shift()?.(rest === "" ? undefined : rest.replace(/\r$/, ""));
+    }
+  };
+
+  stream.on("data", (chunk: Buffer | string) => {
+    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    drain();
+  });
+  stream.on("end", () => {
+    ended = true;
+    drain();
+  });
+  stream.resume();
+
+  return () =>
+    new Promise((resolvePromise) => {
+      waiters.push(resolvePromise);
+      drain();
+    });
+}
+
+// ============================================================================
+// Polling + rendering helpers
+// ============================================================================
+
+/**
+ * Poll deployment status every `pollIntervalMs` until it lands in
+ * `terminal` (single-line progress on a TTY, one line per transition
+ * otherwise). Throws DeployApiError on request failures or timeout.
+ */
+async function pollUntil(
+  ctx: DeployCliContext,
+  slug: string,
+  terminal: ReadonlySet<DeploymentStatus>
+): Promise<DeploymentDetail> {
+  const startedAt = Date.now();
+  const tty = process.stderr.isTTY === true;
+  let lastStatus: DeploymentStatus | undefined;
+  let sawProgress = false;
+
+  const report = (status: DeploymentStatus): void => {
+    if (ctx.json) {
+      return;
+    }
+    const elapsed = Math.round((Date.now() - startedAt) / 1000);
+    if (tty) {
+      ctx.err(`\r\x1b[2K${slug}: ${status} (${elapsed}s)`);
+      sawProgress = true;
+    } else if (status !== lastStatus) {
+      ctx.err(`${slug}: ${status}\n`);
+    }
+    lastStatus = status;
+  };
+  const finishProgressLine = (): void => {
+    if (tty && sawProgress) {
+      ctx.err("\n");
+    }
+  };
+
+  for (;;) {
+    const detail = await ctx.client
+      .getDeployment({ teamId: ctx.teamId, slug })
+      .catch((error: unknown) => {
+        finishProgressLine();
+        throw error;
+      });
+    report(detail.status);
+    if (terminal.has(detail.status)) {
+      finishProgressLine();
+      return detail;
+    }
+    if (Date.now() - startedAt >= ctx.timeoutMs) {
+      finishProgressLine();
+      throw new DeployApiError(
+        `Timed out after ${Math.round(ctx.timeoutMs / 1000)}s waiting for ${slug} (last status: ${detail.status}). It may still converge — check \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.`,
+        0
+      );
+    }
+    await sleep(ctx.pollIntervalMs);
+  }
+}
+
+function aliasTokenBlock(aliasToken: string): string {
+  return (
+    `\n  Alias token (shown ONCE — save it now, it cannot be retrieved again):\n\n` +
+    `    ${aliasToken}\n\n` +
+    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL.\n` +
+    `  Lost tokens: \`${CLI} rotate-token <slug>\` mints a replacement.\n\n`
+  );
+}
+
+function renderApiError(error: unknown, err: (text: string) => void): number {
+  if (error instanceof DeployApiError) {
+    err(`${error.message}\n`);
+    return 1;
+  }
+  throw error;
+}
+
+function renderTable(header: string[], rows: string[][]): string {
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((row) => (row[i] ?? "").length))
+  );
+  const renderRow = (row: string[]): string =>
+    row
+      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+      .join("  ")
+      .trimEnd();
+  return [renderRow(header), ...rows.map(renderRow)].join("\n");
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}