@miosa/sdk 1.2.5 → 1.2.6

package/src/resources/deployments.ts

@@ -1,1208 +0,0 @@
-/**
- * Deployments resource — sandbox→production publishing surface.
- *
- * Backend phase status:
- *   - list / get / create / update / delete / env: repo deployment surface.
- *   - publish / versions.* / releases.* / rollback / domains.*: live release surface.
- *   - runtimeInstances.*: dynamic runtime status/log inspection.
- *   - publishFromSandbox: direct sandbox -> deployment bridge.
- *
- * See docs/deploy/* for the conceptual model.
- */
-
-import { randomUUID } from "node:crypto";
-
-import type { HttpClient } from "../http.js";
-
-// ── Branded IDs ─────────────────────────────────────────────────────────────
-
-export type DeploymentId = string & { readonly __brand: "DeploymentId" };
-export type DeploymentVersionId = string & {
-  readonly __brand: "DeploymentVersionId";
-};
-export type DeploymentReleaseId = string & {
-  readonly __brand: "DeploymentReleaseId";
-};
-export type DeploymentServiceId = string & {
-  readonly __brand: "DeploymentServiceId";
-};
-export type RuntimeInstanceId = string & {
-  readonly __brand: "RuntimeInstanceId";
-};
-
-// ── States / enums ──────────────────────────────────────────────────────────
-
-export type DeploymentState =
-  | "pending"
-  | "building"
-  | "running"
-  | "stopped"
-  | "failed";
-
-export type DeploymentVersionKind = "static" | "dynamic" | "sandbox_backed";
-
-export type DeploymentVersionState =
-  | "created"
-  | "building"
-  | "ready"
-  | "failed"
-  | "archived";
-
-export type DeploymentSourceType = "repo" | "sandbox" | "upload";
-
-export type DeploymentProduct = "miosa_deploy" | "docker_deploy";
-
-export type DeploymentServiceType =
-  | "static_web"
-  | "web"
-  | "api"
-  | "function"
-  | "worker"
-  | "cron"
-  | "postgres"
-  | "redis"
-  | "bucket"
-  | "volume";
-
-export type RuntimeInstanceState =
-  | "provisioning"
-  | "starting"
-  | "healthy"
-  | "unhealthy"
-  | "error"
-  | "stopped"
-  | "destroyed";
-
-// ── Shared attribution ──────────────────────────────────────────────────────
-
-export interface ExternalAttribution {
-  externalWorkspaceId?: string;
-  external_workspace_id?: string;
-  externalUserId?: string;
-  external_user_id?: string;
-  externalProjectId?: string;
-  external_project_id?: string;
-}
-
-// ── Resource shapes ─────────────────────────────────────────────────────────
-
-export interface DeploymentData {
-  id: DeploymentId;
-  tenant_id: string;
-  owner_id?: string;
-  name: string;
-  slug: string;
-  /**
-   * @deprecated — repo-based model. New deployments use source_type: "sandbox"
-   * with `source_sandbox_id` on the version row. Will become nullable.
-   */
-  repo_url?: string;
-  repo_provider?: "github";
-  branch?: string;
-  build_command?: string | null;
-  run_command?: string | null;
-  runtime_image?: string | null;
-  current_build_id?: string | null;
-  active_version_id?: string | null;
-  source_type?: DeploymentSourceType;
-  state: DeploymentState;
-  auto_deploy?: boolean;
-  custom_domain_id?: string | null;
-  linked_database_id?: string | null;
-  deployment_product?: DeploymentProduct | string | null;
-  docker_deploy_host_id?: string | null;
-  metadata?: Record<string, unknown>;
-  external_workspace_id?: string | null;
-  external_user_id?: string | null;
-  external_project_id?: string | null;
-  public_url?: string | null;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export type DeploymentDatabaseRequest =
-  | boolean
-  | {
-      engine?: "postgresql" | "mysql" | "redis" | "qdrant";
-      size?: "xs" | "small" | "medium" | "large";
-      storage_mb?: number;
-      region?: string;
-    };
-
-export interface DeploymentVersionData {
-  id: DeploymentVersionId;
-  deployment_id: DeploymentId;
-  tenant_id: string;
-  created_by?: string | null;
-  source_sandbox_id?: string | null;
-  build_id?: string | null;
-  version_number: number;
-  kind: DeploymentVersionKind;
-  state: DeploymentVersionState;
-  artifact_uri?: string | null;
-  artifact_manifest?: Record<string, unknown>;
-  artifact_sha256?: string | null;
-  runtime_image?: string | null;
-  runtime_command?: string | null;
-  runtime_port?: number | null;
-  health_check_path?: string | null;
-  build_log_uri?: string | null;
-  metadata?: Record<string, unknown>;
-  promoted_at?: string | null;
-  archived_at?: string | null;
-  external_workspace_id?: string | null;
-  external_user_id?: string | null;
-  external_project_id?: string | null;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export interface DeploymentReleaseData {
-  id: DeploymentReleaseId;
-  deployment_id?: DeploymentId;
-  environment_id?: string | null;
-  deployment_version_id: DeploymentVersionId;
-  service_id?: DeploymentServiceId | null;
-  tenant_id: string;
-  external_workspace_id?: string | null;
-  external_user_id?: string | null;
-  external_project_id?: string | null;
-  source_sandbox_id?: string | null;
-  build_id?: string | null;
-  kind: "static" | "oci" | "rootfs" | string;
-  state?: string;
-  artifact_uri?: string | null;
-  artifact_sha256?: string | null;
-  artifact_manifest?: Record<string, unknown>;
-  storage_backend?: string | null;
-  storage_uri?: string;
-  sha256?: string;
-  size_bytes?: number;
-  start_command?: string | null;
-  port?: number | null;
-  health_check_path?: string | null;
-  build_log_uri?: string | null;
-  metadata?: Record<string, unknown>;
-  ready_at?: string | null;
-  archived_at?: string | null;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export interface DeploymentServiceData {
-  id: DeploymentServiceId;
-  deployment_id: DeploymentId;
-  environment_id?: string | null;
-  tenant_id: string;
-  type: DeploymentServiceType;
-  name?: string | null;
-  desired_replicas?: number;
-  state: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface RuntimeInstanceData {
-  id: RuntimeInstanceId;
-  deployment_id?: DeploymentId;
-  environment_id?: string | null;
-  service_id?: DeploymentServiceId | null;
-  release_id?: DeploymentReleaseId;
-  tenant_id: string;
-  external_workspace_id?: string | null;
-  external_user_id?: string | null;
-  external_project_id?: string | null;
-  host_id?: string | null;
-  node_id?: string | null;
-  vm_id?: string | null;
-  desired_state?: string | null;
-  state: RuntimeInstanceState;
-  ip_address?: string | null;
-  port?: number | null;
-  health_check_path?: string | null;
-  last_health_check_at?: string | null;
-  last_heartbeat_at?: string | null;
-  started_at?: string | null;
-  stopped_at?: string | null;
-  error_message?: string | null;
-  restart_count?: number;
-  cpu_limit_millicores?: number | null;
-  memory_limit_mb?: number | null;
-  runtime_log_path?: string | null;
-  metadata?: Record<string, unknown>;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export interface DeploymentBuildData {
-  id: string;
-  deployment_id: DeploymentId;
-  commit_sha?: string | null;
-  commit_message?: string | null;
-  triggered_by?: string;
-  state: string;
-  started_at?: string | null;
-  finished_at?: string | null;
-  duration_ms?: number | null;
-  log_url?: string | null;
-  image_digest?: string | null;
-  error_message?: string | null;
-  external_workspace_id?: string | null;
-  external_user_id?: string | null;
-  external_project_id?: string | null;
-  created_at?: string;
-}
-
-// ── Request / response payloads ─────────────────────────────────────────────
-
-export interface DeploymentListParams extends ExternalAttribution {
-  project_id?: string;
-  projectId?: string;
-  state?: DeploymentState | string;
-  limit?: number;
-  cursor?: string;
-}
-
-export interface DeploymentCreateParams extends ExternalAttribution {
-  name: string;
-  /** Current backend create route is repo-backed; project IDs are attribution, not route ownership. */
-  project_id?: string;
-  projectId?: string;
-  /** @deprecated Ignored by the backend create route. Use sandbox.deploy() for sandbox-backed deployments. */
-  source_type?: DeploymentSourceType;
-  /** @deprecated Ignored by the backend create route. Use sandbox.deploy() for sandbox-backed deployments. */
-  sourceType?: DeploymentSourceType;
-  repo_url?: string;
-  repoUrl?: string;
-  branch?: string;
-  build_command?: string;
-  buildCommand?: string;
-  run_command?: string;
-  runCommand?: string;
-  auto_deploy?: boolean;
-  autoDeploy?: boolean;
-  database?: DeploymentDatabaseRequest;
-  docker_deploy_template_id?: string;
-  dockerDeployTemplateId?: string;
-  metadata?: Record<string, unknown>;
-  idempotencyKey?: string;
-}
-
-export interface DockerDeployCreateParams extends DeploymentCreateParams {}
-
-export interface DockerDeployHostData {
-  id: string;
-  tenant_id?: string;
-  workspace_id?: string | null;
-  computer_id?: string | null;
-  fleet_node_id?: string | null;
-  runtime_base_url?: string | null;
-  status?: string;
-  appliance_status?: string | null;
-  appliance_version?: string | null;
-  appliance_image?: string | null;
-  agent_configured?: boolean;
-  last_health_check_at?: string | null;
-  created_at?: string;
-  updated_at?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface DockerDeployHostListParams {
-  workspace_id?: string;
-  workspaceId?: string;
-}
-
-export interface DockerDeployHostEnsureParams {
-  workspace_id: string;
-  workspaceId?: string;
-  region?: string;
-  size?: string;
-  appliance_image?: string;
-  applianceImage?: string;
-  metadata?: Record<string, unknown>;
-  idempotencyKey?: string;
-}
-
-export interface DockerDeployTemplateData {
-  id: string;
-  name: string;
-  summary?: string;
-  description?: string;
-  category?: string;
-  runtime?: string;
-  framework?: string;
-  build_command?: string | null;
-  run_command?: string | null;
-  ports?: number[];
-  env?: Record<string, string>;
-  files?: Record<string, string>;
-  design_md?: string | null;
-  design_source_url?: string | null;
-  design_sources?: string[];
-  design_reference_presets?: DockerDeployDesignReferencePreset[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface DockerDeployDesignReferencePreset {
-  id: string;
-  name: string;
-  summary: string;
-  best_for?: string[];
-}
-
-export interface DockerDeployTemplateListParams {
-  category?: string;
-  runtime?: string;
-  framework?: string;
-  includePreview?: boolean;
-  include_preview?: boolean;
-}
-
-export interface DockerDeployDoctorParams {
-  /** Probe the deployment public URL after checking control-plane metadata. Default: true. */
-  probe?: boolean;
-  /** Path to request on the public URL. Default: "/". */
-  probePath?: string;
-  /** Public URL probe timeout in milliseconds. Default: 20_000. */
-  timeoutMs?: number;
-  /** Test hook or custom runtime fetch implementation. */
-  fetchImpl?: typeof fetch;
-}
-
-export interface DockerDeployDoctorCheck {
-  name: string;
-  ok: boolean;
-  message: string;
-  data?: Record<string, unknown>;
-}
-
-export interface DockerDeployDoctorProbe {
-  url: string;
-  status: number | null;
-  ok: boolean;
-  responseSnippet: string;
-  gatewayJson?: boolean;
-}
-
-export interface DockerDeployDoctorResult {
-  ok: boolean;
-  deployment: DeploymentData;
-  host?: DockerDeployHostData;
-  publicUrl?: string | null;
-  checks: DockerDeployDoctorCheck[];
-  probe?: DockerDeployDoctorProbe;
-}
-
-export interface DeploymentUpdateParams {
-  name?: string;
-  branch?: string;
-  build_command?: string;
-  buildCommand?: string;
-  run_command?: string;
-  runCommand?: string;
-  auto_deploy?: boolean;
-  autoDeploy?: boolean;
-}
-
-export interface PublishParams extends ExternalAttribution {
-  sourceSandboxId: string;
-  source_sandbox_id?: string;
-  name?: string;
-  deploymentId?: string;
-  deployment_id?: string;
-  /** @deprecated Reserved for dynamic runtime publish; ignored by current static publish route. */
-  kind?: "auto" | "static" | "dynamic";
-  /** @deprecated Reserved for deployment environments; ignored by current static publish route. */
-  environment?: "production" | "staging" | string;
-  outputPath?: string;
-  output_path?: string;
-  /** @deprecated Current /deployments/:id/publish snapshots /workspace internally. */
-  sourceSnapshotPath?: string;
-  /** @deprecated Current /deployments/:id/publish snapshots /workspace internally. */
-  source_snapshot_path?: string;
-  entrypoint?: string;
-  promote?: boolean;
-  domain?: string;
-  customDomain?: string;
-  custom_domain?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  buildCommand?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  build_command?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  runCommand?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  run_command?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  port?: number;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  healthCheckPath?: string;
-  /** @deprecated Reserved for dynamic runtime publish. */
-  health_check_path?: string;
-  deploymentType?: DeploymentProduct | string;
-  deployment_type?: DeploymentProduct | string;
-  dockerDeployTemplateId?: string;
-  docker_deploy_template_id?: string;
-  /** @deprecated Reserved for managed data-service binding. */
-  dataServices?: string[];
-  /** @deprecated Reserved for managed data-service binding. */
-  data_services?: string[];
-  idempotencyKey?: string;
-}
-
-export interface PublishResult {
-  deployment: DeploymentData;
-  version: DeploymentVersionData;
-  release?: DeploymentReleaseData;
-  services?: DeploymentServiceData[];
-  promoted: boolean;
-}
-
-export type PublishFromSandboxParams = Omit<
-  PublishParams,
-  "sourceSandboxId" | "source_sandbox_id"
-> & {
-  sourceSandboxId?: string;
-  source_sandbox_id?: string;
-};
-
-export interface RollbackParams {
-  versionId?: string;
-  version_id?: string;
-  idempotencyKey?: string;
-}
-
-export interface VersionListParams extends ExternalAttribution {
-  state?: DeploymentVersionState | string;
-  limit?: number;
-  cursor?: string;
-}
-
-export interface RuntimeLogsResult {
-  runtime_instance_id?: string;
-  deployment_id?: string;
-  log_path?: string;
-  logs: string;
-}
-
-export interface AddDomainParams extends ExternalAttribution {
-  redirectPolicy?: "none" | "www_to_apex" | "apex_to_www";
-  redirect_policy?: "none" | "www_to_apex" | "apex_to_www";
-  idempotencyKey?: string;
-}
-
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-function attributionBody(p: ExternalAttribution): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  const ws = p.externalWorkspaceId ?? p.external_workspace_id;
-  const usr = p.externalUserId ?? p.external_user_id;
-  const proj = p.externalProjectId ?? p.external_project_id;
-  if (ws !== undefined) out.external_workspace_id = ws;
-  if (usr !== undefined) out.external_user_id = usr;
-  if (proj !== undefined) out.external_project_id = proj;
-  return out;
-}
-
-function idempotencyKey(key?: string): string {
-  return key ?? randomUUID();
-}
-
-function unwrap<T>(payload: { data?: T } | T): T {
-  if (payload && typeof payload === "object" && "data" in (payload as object)) {
-    return (payload as { data: T }).data;
-  }
-  return payload as T;
-}
-
-function listItems<T>(
-  payload: { data?: T[] } | { items?: T[] } | T[] | unknown,
-  candidateKeys: string[] = ["items", "deployments", "versions", "domains"],
-): T[] {
-  if (Array.isArray(payload)) return payload;
-  if (!payload || typeof payload !== "object") return [];
-  const p = payload as Record<string, unknown>;
-  if (Array.isArray(p.data)) return p.data as T[];
-  for (const key of candidateKeys) {
-    if (Array.isArray(p[key])) return p[key] as T[];
-  }
-  return [];
-}
-
-function stripUndefined(
-  input: Record<string, unknown>,
-): Record<string, unknown> {
-  return Object.fromEntries(
-    Object.entries(input).filter(([, v]) => v !== undefined),
-  );
-}
-
-function dockerDeployMetadata(
-  metadata: Record<string, unknown> | undefined,
-  templateId?: string,
-): Record<string, unknown> {
-  return stripUndefined({
-    ...(metadata ?? {}),
-    deployment_product: "docker_deploy",
-    docker_deploy_template_id: templateId,
-  });
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function runtimeMetadata(
-  metadata: Record<string, unknown>,
-): Record<string, unknown> | undefined {
-  const runtime = metadata.runtime;
-  return isRecord(runtime) ? runtime : undefined;
-}
-
-function publicProbeUrl(publicUrl: string, probePath: string): string {
-  const url = new URL(publicUrl);
-  const normalizedPath = probePath.startsWith("/") ? probePath : `/${probePath}`;
-  url.pathname = normalizedPath;
-  return url.toString();
-}
-
-function looksLikeMiosaGatewayJson(body: string): boolean {
-  try {
-    const parsed = JSON.parse(body) as unknown;
-    return (
-      isRecord(parsed) &&
-      parsed.ok === true &&
-      typeof parsed.run_id === "string" &&
-      Object.keys(parsed).every((key) => ["ok", "run_id"].includes(key))
-    );
-  } catch {
-    return false;
-  }
-}
-
-function addDoctorCheck(
-  checks: DockerDeployDoctorCheck[],
-  name: string,
-  ok: boolean,
-  message: string,
-  data?: Record<string, unknown>,
-): void {
-  const check: DockerDeployDoctorCheck = { name, ok, message };
-  if (data !== undefined) check.data = data;
-  checks.push(check);
-}
-
-// ── Sub-resources ──────────────────────────────────────────────────────────
-
-export class DeploymentVersions {
-  constructor(
-    private readonly http: HttpClient,
-    private readonly deploymentId: string,
-  ) {}
-
-  async list(params: VersionListParams = {}): Promise<DeploymentVersionData[]> {
-    const query = stripUndefined({
-      state: params.state,
-      limit: params.limit,
-      cursor: params.cursor,
-      ...attributionBody(params),
-    });
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/versions`,
-      query as Record<string, string | number | boolean | undefined>,
-    );
-    return listItems<DeploymentVersionData>(data);
-  }
-
-  async get(versionId: string): Promise<DeploymentVersionData> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/versions/${versionId}`,
-    );
-    return unwrap(data) as DeploymentVersionData;
-  }
-
-  async promote(
-    versionId: string,
-    opts: { environment?: string; idempotencyKey?: string } = {},
-  ): Promise<DeploymentData> {
-    const body = stripUndefined({ environment: opts.environment });
-    const data = await this.http.request<unknown>(
-      `/deployments/${this.deploymentId}/versions/${versionId}/promote`,
-      {
-        method: "POST",
-        body,
-        headers: { "Idempotency-Key": idempotencyKey(opts.idempotencyKey) },
-      },
-    );
-    return unwrap(data) as DeploymentData;
-  }
-}
-
-export class DeploymentReleases {
-  constructor(
-    private readonly http: HttpClient,
-    private readonly deploymentId: string,
-  ) {}
-
-  async list(): Promise<DeploymentReleaseData[]> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/releases`,
-    );
-    return listItems<DeploymentReleaseData>(data, ["releases"]);
-  }
-
-  async get(releaseId: string): Promise<DeploymentReleaseData> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/releases/${releaseId}`,
-    );
-    return unwrap(data) as DeploymentReleaseData;
-  }
-}
-
-export class DeploymentRuntimeInstances {
-  constructor(
-    private readonly http: HttpClient,
-    private readonly deploymentId: string,
-  ) {}
-
-  async list(): Promise<RuntimeInstanceData[]> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/runtime-instances`,
-    );
-    return listItems<RuntimeInstanceData>(data, ["runtime_instances"]);
-  }
-
-  async get(instanceId: string): Promise<RuntimeInstanceData> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/runtime-instances/${instanceId}`,
-    );
-    return unwrap(data) as RuntimeInstanceData;
-  }
-
-  async logs(instanceId: string, lines = 100): Promise<RuntimeLogsResult> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/runtime-instances/${instanceId}/logs`,
-      { lines },
-    );
-    const unwrapped = unwrap(data) as Record<string, unknown>;
-    const result: RuntimeLogsResult = { logs: String(unwrapped.logs ?? "") };
-    if (typeof unwrapped.runtime_instance_id === "string") {
-      result.runtime_instance_id = unwrapped.runtime_instance_id;
-    }
-    if (typeof unwrapped.deployment_id === "string") {
-      result.deployment_id = unwrapped.deployment_id;
-    }
-    if (typeof unwrapped.log_path === "string") {
-      result.log_path = unwrapped.log_path;
-    }
-    return result;
-  }
-}
-
-export class DeploymentDomains {
-  constructor(
-    private readonly http: HttpClient,
-    private readonly deploymentId: string,
-  ) {}
-
-  async add(
-    domain: string,
-    params: AddDomainParams = {},
-  ): Promise<Record<string, unknown>> {
-    const body = {
-      domain,
-      redirect_policy: params.redirectPolicy ?? params.redirect_policy,
-      ...attributionBody(params),
-    };
-    const data = await this.http.request<unknown>(
-      `/deployments/${this.deploymentId}/domains`,
-      {
-        method: "POST",
-        body: stripUndefined(body),
-        headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-      },
-    );
-    return unwrap(data) as Record<string, unknown>;
-  }
-
-  async list(
-    filters: ExternalAttribution = {},
-  ): Promise<Record<string, unknown>[]> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${this.deploymentId}/domains`,
-      attributionBody(filters) as Record<
-        string,
-        string | number | boolean | undefined
-      >,
-    );
-    return listItems<Record<string, unknown>>(data);
-  }
-
-  async verify(domainId: string): Promise<Record<string, unknown>> {
-    const data = await this.http.post<unknown>(
-      `/deployments/${this.deploymentId}/domains/${domainId}/verify`,
-    );
-    return unwrap(data) as Record<string, unknown>;
-  }
-
-  async delete(domainId: string): Promise<void> {
-    await this.http.delete<unknown>(
-      `/deployments/${this.deploymentId}/domains/${domainId}`,
-    );
-  }
-}
-
-// ── Main resource ──────────────────────────────────────────────────────────
-
-export class Deployments {
-  constructor(private readonly http: HttpClient) {}
-
-  async list(params: DeploymentListParams = {}): Promise<DeploymentData[]> {
-    const projectId = params.projectId ?? params.project_id;
-    const query = stripUndefined({
-      project_id: projectId,
-      state: params.state,
-      limit: params.limit,
-      cursor: params.cursor,
-      ...attributionBody(params),
-    });
-    const data = await this.http.get<unknown>(
-      "/deployments",
-      query as Record<string, string | number | boolean | undefined>,
-    );
-    return listItems<DeploymentData>(data);
-  }
-
-  async get(deploymentId: string): Promise<DeploymentData> {
-    const data = await this.http.get<unknown>(`/deployments/${deploymentId}`);
-    return unwrap(data) as DeploymentData;
-  }
-
-  async create(params: DeploymentCreateParams): Promise<DeploymentData> {
-    const body = stripUndefined({
-      name: params.name,
-      repo_url: params.repoUrl ?? params.repo_url,
-      branch: params.branch,
-      build_command: params.buildCommand ?? params.build_command,
-      run_command: params.runCommand ?? params.run_command,
-      auto_deploy: params.autoDeploy ?? params.auto_deploy,
-      database: params.database,
-      docker_deploy_template_id:
-        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
-      metadata: params.metadata,
-      ...attributionBody(params),
-    });
-    const data = await this.http.request<unknown>("/deployments", {
-      method: "POST",
-      body,
-      headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-    });
-    return unwrap(data) as DeploymentData;
-  }
-
-  /**
-   * Create a deployment that runs on the workspace's dedicated Docker Deploy
-   * runtime. It uses the same /deployments API as MIOSA Deploy, but marks the
-   * deployment so the control plane attaches it to the workspace Docker host.
-   */
-  async createDockerDeploy(
-    params: DockerDeployCreateParams,
-  ): Promise<DeploymentData> {
-    const templateId =
-      params.dockerDeployTemplateId ?? params.docker_deploy_template_id;
-    return this.create({
-      ...params,
-      metadata: dockerDeployMetadata(params.metadata, templateId),
-    });
-  }
-
-  async listDockerDeployHosts(
-    params: DockerDeployHostListParams = {},
-  ): Promise<DockerDeployHostData[]> {
-    const data = await this.http.get<unknown>(
-      "/docker-deploy/hosts",
-      stripUndefined({
-        workspace_id: params.workspaceId ?? params.workspace_id,
-      }) as Record<string, string | number | boolean | undefined>,
-    );
-    return listItems<DockerDeployHostData>(data, ["hosts", "items"]);
-  }
-
-  async ensureDockerDeployHost(
-    params: DockerDeployHostEnsureParams,
-  ): Promise<DockerDeployHostData> {
-    const data = await this.http.request<unknown>("/docker-deploy/hosts/ensure", {
-      method: "POST",
-      body: stripUndefined({
-        workspace_id: params.workspaceId ?? params.workspace_id,
-        region: params.region,
-        size: params.size,
-        appliance_image: params.applianceImage ?? params.appliance_image,
-        metadata: params.metadata,
-      }),
-      headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-    });
-    return unwrap(data) as DockerDeployHostData;
-  }
-
-  async getDockerDeployHost(hostId: string): Promise<DockerDeployHostData> {
-    const data = await this.http.get<unknown>(`/docker-deploy/hosts/${hostId}`);
-    return unwrap(data) as DockerDeployHostData;
-  }
-
-  /**
-   * Verify a Docker Deploy deployment end-to-end.
-   *
-   * This checks the deployment product marker, Docker Deploy host linkage,
-   * appliance health, route runtime metadata, and optionally the public URL.
-   * It is intentionally agent-friendly: use this after sandbox.deployDocker()
-   * or createDockerDeploy() before telling a user the app is live.
-   */
-  async doctorDockerDeploy(
-    deploymentId: string,
-    params: DockerDeployDoctorParams = {},
-  ): Promise<DockerDeployDoctorResult> {
-    const checks: DockerDeployDoctorCheck[] = [];
-    const deployment = await this.get(deploymentId);
-    const metadata = isRecord(deployment.metadata) ? deployment.metadata : {};
-    const product =
-      stringValue(deployment.deployment_product) ??
-      stringValue(metadata.deployment_product);
-    const hostId =
-      stringValue(deployment.docker_deploy_host_id) ??
-      stringValue(metadata.docker_deploy_host_id);
-
-    addDoctorCheck(
-      checks,
-      "deployment_product",
-      product === "docker_deploy",
-      product === "docker_deploy"
-        ? "Deployment is marked as Docker Deploy."
-        : `Expected deployment_product=docker_deploy, got ${product ?? "missing"}.`,
-      { product: product ?? null },
-    );
-
-    addDoctorCheck(
-      checks,
-      "docker_deploy_host_id",
-      !!hostId,
-      hostId
-        ? "Deployment is linked to a Docker Deploy appliance host."
-        : "Deployment has no docker_deploy_host_id.",
-      { docker_deploy_host_id: hostId ?? null },
-    );
-
-    let host: DockerDeployHostData | undefined;
-    if (hostId) {
-      try {
-        host = await this.getDockerDeployHost(hostId);
-        const status = host.status ?? null;
-        const applianceStatus = host.appliance_status ?? null;
-        const badHostStates = new Set(["failed", "error", "destroyed"]);
-        const badApplianceStates = new Set(["failed", "error", "unhealthy"]);
-        const ok =
-          !badHostStates.has(String(status)) &&
-          !badApplianceStates.has(String(applianceStatus));
-        addDoctorCheck(
-          checks,
-          "docker_deploy_host_health",
-          ok,
-          ok
-            ? "Docker Deploy host is not reporting a failed state."
-            : `Docker Deploy host is unhealthy: status=${status}, appliance_status=${applianceStatus}.`,
-          { status, appliance_status: applianceStatus },
-        );
-      } catch (err) {
-        addDoctorCheck(
-          checks,
-          "docker_deploy_host_health",
-          false,
-          `Could not fetch Docker Deploy host ${hostId}: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      }
-    }
-
-    const runtime = runtimeMetadata(metadata);
-    const runtimeIp = runtime
-      ? stringValue(runtime.ip) ?? stringValue(runtime.ip_address)
-      : undefined;
-    const runtimePort = runtime?.port;
-    addDoctorCheck(
-      checks,
-      "route_runtime",
-      !!runtimeIp && runtimePort !== undefined && runtimePort !== null,
-      runtimeIp && runtimePort !== undefined && runtimePort !== null
-        ? "Deployment route metadata points at a runtime target."
-        : "Deployment metadata has no runtime ip/port target.",
-      { ip: runtimeIp ?? null, port: runtimePort ?? null },
-    );
-
-    const publicUrl =
-      stringValue(deployment.public_url) ?? stringValue(metadata.public_url);
-    addDoctorCheck(
-      checks,
-      "public_url",
-      !!publicUrl,
-      publicUrl
-        ? "Deployment has a public URL."
-        : "Deployment has no public URL to probe.",
-      { public_url: publicUrl ?? null },
-    );
-
-    let probe: DockerDeployDoctorProbe | undefined;
-    if (params.probe !== false && publicUrl) {
-      const fetchImpl = params.fetchImpl ?? fetch;
-      const url = publicProbeUrl(publicUrl, params.probePath ?? "/");
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 20_000);
-      try {
-        const response = await fetchImpl(url, {
-          headers: { Accept: "*/*" },
-          signal: controller.signal,
-        });
-        const text = await response.text();
-        const gatewayJson = looksLikeMiosaGatewayJson(text);
-        const ok = response.ok && !gatewayJson;
-        probe = {
-          url,
-          status: response.status,
-          ok,
-          responseSnippet: text.slice(0, 500),
-        };
-        if (gatewayJson) probe.gatewayJson = true;
-        addDoctorCheck(
-          checks,
-          "public_url_probe",
-          ok,
-          ok
-            ? `Public URL returned HTTP ${response.status}.`
-            : gatewayJson
-              ? "Public URL returned MIOSA gateway JSON instead of the app."
-              : `Public URL returned HTTP ${response.status}.`,
-          { status: response.status, gateway_json: gatewayJson },
-        );
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        probe = { url, status: null, ok: false, responseSnippet: message };
-        addDoctorCheck(
-          checks,
-          "public_url_probe",
-          false,
-          `Public URL probe failed: ${message}`,
-        );
-      } finally {
-        clearTimeout(timer);
-      }
-    }
-
-    const result: DockerDeployDoctorResult = {
-      ok: checks.every((check) => check.ok),
-      deployment,
-      checks,
-    };
-    if (host) result.host = host;
-    if (publicUrl !== undefined) result.publicUrl = publicUrl;
-    if (probe) result.probe = probe;
-    return result;
-  }
-
-  async listDockerDeployTemplates(
-    params: DockerDeployTemplateListParams = {},
-  ): Promise<DockerDeployTemplateData[]> {
-    const query: Record<string, string | number | boolean | undefined> = {
-      category: params.category,
-      runtime: params.runtime,
-      framework: params.framework,
-      include_preview: params.includePreview ?? params.include_preview,
-    };
-    const data = await this.http.get<unknown>(
-      "/docker-deploy/templates",
-      stripUndefined(query) as Record<string, string | number | boolean | undefined>,
-    );
-    const templates = unwrap<any>(data);
-    if (Array.isArray(templates)) return templates as DockerDeployTemplateData[];
-    return ((templates?.templates ?? templates?.items ?? templates?.data ?? []) ||
-      []) as DockerDeployTemplateData[];
-  }
-
-  async getDockerDeployTemplate(
-    templateId: string,
-  ): Promise<DockerDeployTemplateData> {
-    const data = await this.http.get<unknown>(
-      `/docker-deploy/templates/${templateId}`,
-    );
-    return unwrap(data) as DockerDeployTemplateData;
-  }
-
-  async update(
-    deploymentId: string,
-    params: DeploymentUpdateParams,
-  ): Promise<DeploymentData> {
-    const body = stripUndefined({
-      name: params.name,
-      branch: params.branch,
-      build_command: params.buildCommand ?? params.build_command,
-      run_command: params.runCommand ?? params.run_command,
-      auto_deploy: params.autoDeploy ?? params.auto_deploy,
-    });
-    const data = await this.http.patch<unknown>(
-      `/deployments/${deploymentId}`,
-      body,
-    );
-    return unwrap(data) as DeploymentData;
-  }
-
-  async delete(deploymentId: string): Promise<void> {
-    await this.http.delete<unknown>(`/deployments/${deploymentId}`);
-  }
-
-  async publish(
-    deploymentId: string,
-    params: PublishParams,
-  ): Promise<PublishResult> {
-    const body = stripUndefined({
-      source_sandbox_id: params.sourceSandboxId ?? params.source_sandbox_id,
-      output_path: params.outputPath ?? params.output_path,
-      entrypoint: params.entrypoint,
-      promote: params.promote,
-      build_command: params.buildCommand ?? params.build_command,
-      run_command: params.runCommand ?? params.run_command,
-      port: params.port,
-      health_check_path: params.healthCheckPath ?? params.health_check_path,
-      deployment_type: params.deploymentType ?? params.deployment_type,
-      docker_deploy_template_id:
-        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
-      data_services: params.dataServices ?? params.data_services,
-      ...attributionBody(params),
-    });
-    const data = await this.http.request<unknown>(
-      `/deployments/${deploymentId}/publish`,
-      {
-        method: "POST",
-        body,
-        headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-      },
-    );
-    return unwrap(data) as PublishResult;
-  }
-
-  /**
-   * Backward-compatible bridge: POST /sandboxes/:id/deploy. Works today;
-   * returns either release-backed or sandbox-backed depending on backend
-   * phase. Prefer `publish()` once Phase 2B/3 lands.
-   */
-  async publishFromSandbox(
-    sandboxId: string,
-    params: PublishFromSandboxParams = {},
-  ): Promise<Record<string, unknown>> {
-    const body = stripUndefined({
-      name: params.name,
-      deployment_id: params.deploymentId ?? params.deployment_id,
-      output_path: params.outputPath ?? params.output_path,
-      source_snapshot_path:
-        params.sourceSnapshotPath ?? params.source_snapshot_path,
-      entrypoint: params.entrypoint,
-      domain: params.domain,
-      custom_domain: params.customDomain ?? params.custom_domain,
-      build_command: params.buildCommand ?? params.build_command,
-      run_command: params.runCommand ?? params.run_command,
-      port: params.port,
-      health_check_path: params.healthCheckPath ?? params.health_check_path,
-      deployment_type: params.deploymentType ?? params.deployment_type,
-      docker_deploy_template_id:
-        params.dockerDeployTemplateId ?? params.docker_deploy_template_id,
-      data_services: params.dataServices ?? params.data_services,
-      ...attributionBody(params),
-    });
-    const data = await this.http.request<unknown>(
-      `/sandboxes/${sandboxId}/deploy`,
-      {
-        method: "POST",
-        body,
-        headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-      },
-    );
-    return unwrap(data) as Record<string, unknown>;
-  }
-
-  async rollback(
-    deploymentId: string,
-    params: RollbackParams = {},
-  ): Promise<DeploymentData> {
-    const body = stripUndefined({
-      version_id: params.versionId ?? params.version_id,
-    });
-    const data = await this.http.request<unknown>(
-      `/deployments/${deploymentId}/rollback`,
-      {
-        method: "POST",
-        body,
-        headers: { "Idempotency-Key": idempotencyKey(params.idempotencyKey) },
-      },
-    );
-    return unwrap(data) as DeploymentData;
-  }
-
-  async listBuilds(deploymentId: string): Promise<DeploymentBuildData[]> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${deploymentId}/builds`,
-    );
-    return listItems<DeploymentBuildData>(data);
-  }
-
-  async getBuild(
-    deploymentId: string,
-    buildId: string,
-  ): Promise<DeploymentBuildData> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${deploymentId}/builds/${buildId}`,
-    );
-    return unwrap(data) as DeploymentBuildData;
-  }
-
-  async listEnv(deploymentId: string): Promise<Record<string, unknown>[]> {
-    const data = await this.http.get<unknown>(
-      `/deployments/${deploymentId}/env`,
-    );
-    return listItems<Record<string, unknown>>(data);
-  }
-
-  async setEnv(
-    deploymentId: string,
-    vars: Record<string, string>,
-    opts: { environment?: string } = {},
-  ): Promise<Record<string, unknown>[]> {
-    const body = stripUndefined({ env: vars, environment: opts.environment });
-    const data = await this.http.post<unknown>(
-      `/deployments/${deploymentId}/env`,
-      body,
-    );
-    return listItems<Record<string, unknown>>(data);
-  }
-
-  versions(deploymentId: string): DeploymentVersions {
-    return new DeploymentVersions(this.http, deploymentId);
-  }
-
-  releases(deploymentId: string): DeploymentReleases {
-    return new DeploymentReleases(this.http, deploymentId);
-  }
-
-  runtimeInstances(deploymentId: string): DeploymentRuntimeInstances {
-    return new DeploymentRuntimeInstances(this.http, deploymentId);
-  }
-
-  runtime_instances(deploymentId: string): DeploymentRuntimeInstances {
-    return this.runtimeInstances(deploymentId);
-  }
-
-  domains(deploymentId: string): DeploymentDomains {
-    return new DeploymentDomains(this.http, deploymentId);
-  }
-}