@cursor/july 0.1.1 → 0.1.2

package/src/internal/cli-deploy.ts

@@ -0,0 +1,940 @@
+/**
+ * `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 {
+  cursorBackendUrl,
+  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 { isAgentProjectDir, loadAgentProject } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import {
+  isValidCursorEventRepo,
+  validateSettableSecretName,
+} from "./hosting.js";
+
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_DEPLOY_TIMEOUT_MS = 10 * 60 * 1000;
+
+export interface DeployCliOptions {
+  dir?: string;
+  slug?: string;
+  /** `--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. */
+  repo?: string;
+  /** deploy `--ref <ref>`: git ref (defaults to the default branch server-side). */
+  ref?: string;
+  /** deploy `--path <agentPath>`: agent directory relative to the repo root. */
+  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;
+  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;
+}
+
+/**
+ * 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 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;
+  }
+  const client = new AgentServeDeployClient({
+    backendUrl: resolved.backendUrl,
+    apiKey: resolved.apiKey,
+    ...(options.fetchImpl === undefined
+      ? {}
+      : { 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,
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { 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;
+    err(
+      `Using team ${teamId}${
+        identity.teamName === undefined ? "" : ` (${identity.teamName})`
+      } — the account's team; pass --team to override.\n`
+    );
+  }
+
+  return {
+    client,
+    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 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) {
+      ctx.err(
+        `Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.\n`
+      );
+      return 1;
+    }
+    slug = derived;
+    ctx.err(`Deploying as "${slug}" (from the directory name).\n`);
+  }
+
+  if (options.repo !== undefined && !options.repo.startsWith("https://")) {
+    ctx.err(
+      `Invalid --repo: ${options.repo} (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;
+    }
+  }
+
+  // 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 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",
+    ...(options.repo === undefined ? {} : { gitRepoUrl: options.repo }),
+    ...(options.ref === undefined ? {} : { gitRef: options.ref }),
+    ...(options.path === undefined ? {} : { agentPath: options.path }),
+    ...(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 (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);
+
+  if (ctx.json) {
+    ctx.out(
+      `${JSON.stringify(
+        accepted.aliasToken === undefined
+          ? detail
+          : { ...detail, aliasToken: accepted.aliasToken },
+        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:  ${aliasUrl}/playground (send X-Agent-Alias-Token)\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));
+}