@prisma/compute-sdk 0.1.0

package/src/compute-client.ts

@@ -0,0 +1,985 @@
+import type { ManagementApiClient } from "@prisma/management-api-sdk";
+import { type InferOk, Result } from "better-result";
+import {
+  InternalApiClient,
+  readUploadUrl,
+  toDeploymentUrl,
+} from "./api-client.ts";
+import { createArchive } from "./archive.ts";
+import type { BuildStrategy } from "./build-strategy.ts";
+import type {
+  DeployInteraction,
+  DeployProgress,
+  DestroyServiceProgress,
+  DestroyVersionInteraction,
+  DestroyVersionProgress,
+  UpdateEnvProgress,
+} from "./callbacks.ts";
+import type { ComputeError } from "./errors.ts";
+import {
+  ApiError,
+  ArtifactError,
+  BuildError,
+  CancelledError,
+  DestroyAggregateError,
+  MissingArgumentError,
+  NoExistingVersionError,
+} from "./errors.ts";
+import { pollVersionStatus } from "./polling.ts";
+import type {
+  PortMapping,
+  ProjectInfo,
+  ResolvedConfig,
+  ServiceDetail,
+  ServiceInfo,
+  VersionDetail,
+  VersionInfo,
+} from "./types.ts";
+import { REGIONS } from "./types.ts";
+
+type VersionDetailData = InferOk<
+  Awaited<ReturnType<InternalApiClient["getVersion"]>>
+>;
+
+export interface DeployOptions {
+  strategy: BuildStrategy;
+  projectId?: string;
+  serviceId?: string;
+  serviceName?: string;
+  region?: string;
+  envVars?: Record<string, string>;
+  portMapping?: PortMapping;
+  timeoutSeconds?: number;
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+  interaction?: DeployInteraction;
+  progress?: DeployProgress;
+}
+
+export interface UpdateEnvOptions {
+  projectId?: string;
+  serviceId?: string;
+  envVars?: Record<string, string>;
+  portMapping?: PortMapping;
+  timeoutSeconds?: number;
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+  interaction?: DeployInteraction;
+  progress?: UpdateEnvProgress;
+}
+
+export interface DestroyVersionOptions {
+  versionId?: string;
+  serviceId?: string;
+  projectId?: string;
+  timeoutSeconds?: number;
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+  interaction?: DestroyVersionInteraction;
+  progress?: DestroyVersionProgress;
+}
+
+export interface DestroyServiceOptions {
+  serviceId: string;
+  keepService?: boolean;
+  timeoutSeconds?: number;
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+  progress?: DestroyServiceProgress;
+}
+
+export interface ListServicesOptions {
+  projectId: string;
+  signal?: AbortSignal;
+}
+
+export interface CreateServiceOptions {
+  projectId: string;
+  serviceName: string;
+  region: string;
+  signal?: AbortSignal;
+}
+
+export interface ShowServiceOptions {
+  serviceId: string;
+  signal?: AbortSignal;
+}
+
+export interface DeleteServiceOptions {
+  serviceId: string;
+  signal?: AbortSignal;
+}
+
+export interface ListProjectsOptions {
+  signal?: AbortSignal;
+}
+
+export interface ListVersionsOptions {
+  serviceId: string;
+  signal?: AbortSignal;
+}
+
+export interface ShowVersionOptions {
+  versionId: string;
+  signal?: AbortSignal;
+}
+
+export interface StartVersionOptions {
+  versionId: string;
+  signal?: AbortSignal;
+}
+
+export interface StopVersionOptions {
+  versionId: string;
+  signal?: AbortSignal;
+}
+
+export interface DeleteVersionOptions {
+  versionId: string;
+  signal?: AbortSignal;
+}
+
+export interface DeployResult {
+  projectId: string;
+  serviceId: string;
+  serviceName: string;
+  region: string;
+  versionId: string;
+  deploymentUrl: string;
+  resolvedConfig: ResolvedConfig;
+}
+
+export interface UpdateEnvResult {
+  projectId: string;
+  serviceId: string;
+  versionId: string;
+  deploymentUrl: string;
+  resolvedConfig: ResolvedConfig;
+}
+
+export interface DestroyVersionResult {
+  versionId: string;
+  previousStatus: string;
+  stopped: boolean;
+  deleted: boolean;
+}
+
+export interface DestroyServiceResult {
+  serviceId: string;
+  deletedVersionIds: string[];
+  serviceDeleted: boolean;
+}
+
+const DEFAULT_TIMEOUT_SECONDS = 120;
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+
+export class ComputeClient {
+  readonly #api: InternalApiClient;
+
+  constructor(managementApiClient: ManagementApiClient) {
+    this.#api = new InternalApiClient(managementApiClient);
+  }
+
+  async deploy(
+    options: DeployOptions,
+  ): Promise<Result<DeployResult, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+
+      const target = yield* Result.await(self.#resolveDeployTarget(options));
+
+      options.progress?.onBuildStart?.();
+      const artifact = yield* Result.await(
+        Result.tryPromise({
+          try: () => options.strategy.execute(),
+          catch: (e) =>
+            new BuildError({
+              message: e instanceof Error ? e.message : String(e),
+            }),
+        }),
+      );
+      options.progress?.onBuildComplete?.(artifact);
+
+      try {
+        yield* self.#checkAborted(options.signal);
+
+        options.progress?.onArchiveCreating?.();
+        const archiveBytes = yield* Result.await(
+          Result.tryPromise({
+            try: () => createArchive(artifact.directory, artifact.entrypoint),
+            catch: (e) =>
+              new ArtifactError({
+                message:
+                  e instanceof Error
+                    ? e.message
+                    : `Archive creation failed: ${String(e)}`,
+                cause: e,
+              }),
+          }),
+        );
+        options.progress?.onArchiveReady?.(archiveBytes.byteLength);
+
+        yield* self.#checkAborted(options.signal);
+
+        const createResponse = yield* Result.await(
+          self.#api.createServiceVersion(
+            target.serviceId,
+            {
+              envVars: options.envVars,
+              portMapping: options.portMapping,
+            },
+            options.signal,
+          ),
+        );
+        options.progress?.onVersionCreated?.(createResponse.id);
+
+        const uploadUrl = readUploadUrl(createResponse);
+        if (!uploadUrl) {
+          return Result.err(
+            new ArtifactError({
+              message: "Version creation did not return an upload URL",
+            }),
+          );
+        }
+
+        yield* self.#checkAborted(options.signal);
+
+        options.progress?.onUploadStart?.();
+        yield* Result.await(self.#uploadArtifact(uploadUrl, archiveBytes));
+        options.progress?.onUploadComplete?.();
+
+        yield* self.#checkAborted(options.signal);
+
+        options.progress?.onStartRequested?.();
+        yield* Result.await(
+          self.#api.startVersion(createResponse.id, options.signal),
+        );
+
+        const pollResult = yield* Result.await(
+          pollVersionStatus(self.#api, createResponse.id, {
+            targetStatus: "running",
+            timeoutSeconds: options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS,
+            pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+            signal: options.signal,
+            onStatusChange: options.progress?.onStatusChange,
+          }),
+        );
+
+        const deploymentUrl = toDeploymentUrl(pollResult.previewDomain);
+        options.progress?.onRunning?.(deploymentUrl);
+
+        return Result.ok({
+          projectId: target.projectId,
+          serviceId: target.serviceId,
+          serviceName: target.serviceName,
+          region: target.region,
+          versionId: createResponse.id,
+          deploymentUrl,
+          resolvedConfig: {
+            projectId: target.projectId,
+            serviceId: target.serviceId,
+            serviceName: target.serviceName,
+            region: target.region,
+            portMapping: options.portMapping,
+          },
+        });
+      } finally {
+        await artifact.cleanup?.();
+      }
+    });
+  }
+
+  async updateEnv(
+    options: UpdateEnvOptions,
+  ): Promise<Result<UpdateEnvResult, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+
+      const target = yield* Result.await(self.#resolveDeployTarget(options));
+
+      const versions = yield* Result.await(
+        self.#api.listServiceVersions(target.serviceId, options.signal),
+      );
+      if (versions.length === 0) {
+        return Result.err(
+          new NoExistingVersionError({ serviceId: target.serviceId }),
+        );
+      }
+
+      yield* self.#checkAborted(options.signal);
+
+      const createResponse = yield* Result.await(
+        self.#api.createServiceVersion(
+          target.serviceId,
+          {
+            envVars: options.envVars,
+            portMapping: options.portMapping,
+            skipCodeUpload: true,
+          },
+          options.signal,
+        ),
+      );
+      options.progress?.onVersionCreated?.(createResponse.id);
+
+      yield* self.#checkAborted(options.signal);
+
+      options.progress?.onStartRequested?.();
+      yield* Result.await(
+        self.#api.startVersion(createResponse.id, options.signal),
+      );
+
+      const pollResult = yield* Result.await(
+        pollVersionStatus(self.#api, createResponse.id, {
+          targetStatus: "running",
+          timeoutSeconds: options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS,
+          pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+          signal: options.signal,
+          onStatusChange: options.progress?.onStatusChange,
+        }),
+      );
+
+      const deploymentUrl = toDeploymentUrl(pollResult.previewDomain);
+      options.progress?.onRunning?.(deploymentUrl);
+
+      return Result.ok({
+        projectId: target.projectId,
+        serviceId: target.serviceId,
+        versionId: createResponse.id,
+        deploymentUrl,
+        resolvedConfig: {
+          projectId: target.projectId,
+          serviceId: target.serviceId,
+          serviceName: target.serviceName,
+          region: target.region,
+          portMapping: options.portMapping,
+        },
+      });
+    });
+  }
+
+  async destroyVersion(
+    options: DestroyVersionOptions,
+  ): Promise<Result<DestroyVersionResult, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+
+      let versionId = options.versionId;
+      let versionDetailsCache: Map<string, VersionDetailData> | undefined;
+
+      if (!versionId) {
+        const serviceId = options.serviceId;
+        if (!serviceId) {
+          return Result.err(new MissingArgumentError({ field: "versionId" }));
+        }
+
+        const versions = yield* Result.await(
+          self.#api.listServiceVersions(serviceId, options.signal),
+        );
+        const versionDetailResults = await Promise.all(
+          versions.map((v) => self.#api.getVersion(v.id, options.signal)),
+        );
+
+        const details: VersionDetailData[] = [];
+        for (const result of versionDetailResults) {
+          if (result.isErr()) return result;
+          details.push(result.value);
+        }
+
+        versionDetailsCache = new Map(details.map((v) => [v.id, v]));
+
+        const versionInfos = details
+          .map(
+            (v): VersionInfo => ({
+              id: v.id,
+              status: v.status,
+              createdAt: v.createdAt,
+              previewDomain: v.previewDomain,
+            }),
+          )
+          .sort(versionSortComparator);
+
+        if (versionInfos.length === 0) {
+          return Result.err(new MissingArgumentError({ field: "versionId" }));
+        }
+
+        if (!options.interaction?.selectVersion) {
+          return Result.err(new MissingArgumentError({ field: "versionId" }));
+        }
+
+        versionId = await options.interaction.selectVersion(versionInfos);
+      }
+
+      const version =
+        versionDetailsCache?.get(versionId) ??
+        (yield* Result.await(self.#api.getVersion(versionId, options.signal)));
+
+      const previousStatus = version.status ?? "unknown";
+      const shouldStop =
+        version.status === "running" || version.status === "provisioning";
+      let stopped = false;
+
+      if (shouldStop) {
+        options.progress?.onStopRequested?.(versionId);
+        yield* Result.await(self.#api.stopVersion(versionId, options.signal));
+
+        yield* Result.await(
+          pollVersionStatus(self.#api, versionId, {
+            targetStatus: "stopped",
+            timeoutSeconds: options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS,
+            pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+            signal: options.signal,
+          }),
+        );
+        stopped = true;
+        options.progress?.onStopped?.(versionId);
+      }
+
+      yield* Result.await(self.#api.deleteVersion(versionId, options.signal));
+      options.progress?.onDeleted?.(versionId);
+
+      return Result.ok({
+        versionId,
+        previousStatus,
+        stopped,
+        deleted: true,
+      });
+    });
+  }
+
+  async destroyService(
+    options: DestroyServiceOptions,
+  ): Promise<Result<DestroyServiceResult, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+
+      const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+      const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+      const versions = yield* Result.await(
+        self.#api.listServiceVersions(options.serviceId, options.signal),
+      );
+      const versionDetailResults = await Promise.all(
+        versions.map((v) => self.#api.getVersion(v.id, options.signal)),
+      );
+
+      const versionDetails: VersionDetailData[] = [];
+      for (const result of versionDetailResults) {
+        if (result.isErr()) return result;
+        versionDetails.push(result.value);
+      }
+
+      const activeVersions = versionDetails.filter(
+        (v) => v.status === "running" || v.status === "provisioning",
+      );
+
+      const succeededIds: string[] = [];
+      const failures: Array<{ versionId: string; error: ComputeError }> = [];
+
+      if (activeVersions.length > 0) {
+        const activeIds = activeVersions.map((v) => v.id);
+        options.progress?.onStoppingVersions?.(activeIds);
+
+        const stopResults = await Promise.all(
+          activeVersions.map((v) =>
+            self.#api.stopVersion(v.id, options.signal),
+          ),
+        );
+
+        const stoppedCandidates: typeof activeVersions = [];
+        for (const [i, result] of stopResults.entries()) {
+          // biome-ignore lint/style/noNonNullAssertion: both lists have the same length
+          const activeVersion = activeVersions[i]!;
+          if (result.isErr()) {
+            failures.push({
+              versionId: activeVersion.id,
+              error: result.error,
+            });
+          } else {
+            stoppedCandidates.push(activeVersion);
+          }
+        }
+
+        if (stoppedCandidates.length > 0) {
+          const pollResults = await Promise.all(
+            stoppedCandidates.map((v) =>
+              pollVersionStatus(self.#api, v.id, {
+                targetStatus: "stopped",
+                timeoutSeconds,
+                pollIntervalMs,
+                signal: options.signal,
+              }),
+            ),
+          );
+
+          for (const [i, result] of pollResults.entries()) {
+            // biome-ignore lint/style/noNonNullAssertion: both lists have the same length
+            const stoppedVersion = stoppedCandidates[i]!;
+            if (result.isErr()) {
+              failures.push({
+                versionId: stoppedVersion.id,
+                error: result.error,
+              });
+            } else {
+              options.progress?.onVersionStopped?.(stoppedVersion.id);
+            }
+          }
+        }
+
+        if (failures.length > 0) {
+          return Result.err(
+            new DestroyAggregateError({
+              succeededVersionIds: succeededIds,
+              failures,
+              serviceDeleted: false,
+            }),
+          );
+        }
+
+        options.progress?.onAllVersionsStopped?.();
+      }
+
+      if (versions.length > 0) {
+        const versionIds = versions.map((v) => v.id);
+        options.progress?.onDeletingVersions?.(versionIds);
+
+        const deleteResults = await Promise.all(
+          versions.map((v) => self.#api.deleteVersion(v.id, options.signal)),
+        );
+
+        for (const [i, result] of deleteResults.entries()) {
+          // biome-ignore lint/style/noNonNullAssertion: both lists have the same length
+          const version = versions[i]!;
+          if (result.isErr()) {
+            failures.push({
+              versionId: version.id,
+              error: result.error,
+            });
+          } else {
+            succeededIds.push(version.id);
+            options.progress?.onVersionDeleted?.(version.id);
+          }
+        }
+
+        if (failures.length > 0) {
+          return Result.err(
+            new DestroyAggregateError({
+              succeededVersionIds: succeededIds,
+              failures,
+              serviceDeleted: false,
+            }),
+          );
+        }
+
+        options.progress?.onAllVersionsDeleted?.();
+      }
+
+      let serviceDeleted = false;
+      if (!options.keepService) {
+        yield* Result.await(
+          self.#api.deleteService(options.serviceId, options.signal),
+        );
+        serviceDeleted = true;
+        options.progress?.onServiceDeleted?.(options.serviceId);
+      }
+
+      return Result.ok({
+        serviceId: options.serviceId,
+        deletedVersionIds: succeededIds,
+        serviceDeleted,
+      });
+    });
+  }
+
+  async listProjects(
+    options: ListProjectsOptions = {},
+  ): Promise<Result<ProjectInfo[], ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const projects = yield* Result.await(
+        self.#api.listProjects(options.signal),
+      );
+      return Result.ok(
+        projects.map(
+          (p): ProjectInfo => ({
+            id: p.id,
+            name: p.name,
+            defaultRegion: p.defaultRegion ?? undefined,
+          }),
+        ),
+      );
+    });
+  }
+
+  async listServices(
+    options: ListServicesOptions,
+  ): Promise<Result<ServiceInfo[], ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const services = yield* Result.await(
+        self.#api.listProjectServices(options.projectId, options.signal),
+      );
+      return Result.ok(
+        services.map(
+          (s): ServiceInfo => ({
+            id: s.id,
+            name: s.name,
+            region: s.region.id,
+            projectId: s.projectId,
+          }),
+        ),
+      );
+    });
+  }
+
+  async createService(
+    options: CreateServiceOptions,
+  ): Promise<Result<ServiceInfo, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const response = yield* Result.await(
+        self.#api.createProjectService(
+          options.projectId,
+          {
+            displayName: options.serviceName,
+            regionId: options.region,
+          },
+          options.signal,
+        ),
+      );
+      return Result.ok({
+        id: response.id,
+        name: response.name,
+        region: response.region.id,
+        projectId: options.projectId,
+      });
+    });
+  }
+
+  async showService(
+    options: ShowServiceOptions,
+  ): Promise<Result<ServiceDetail, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const s = yield* Result.await(
+        self.#api.getService(options.serviceId, options.signal),
+      );
+      return Result.ok({
+        id: s.id,
+        name: s.name,
+        region: s.region.id,
+        projectId: s.projectId,
+        latestVersionId: s.latestVersionId,
+      });
+    });
+  }
+
+  async deleteService(
+    options: DeleteServiceOptions,
+  ): Promise<Result<void, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      yield* Result.await(
+        self.#api.deleteService(options.serviceId, options.signal),
+      );
+      return Result.ok();
+    });
+  }
+
+  async listVersions(
+    options: ListVersionsOptions,
+  ): Promise<Result<VersionInfo[], ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const versions = yield* Result.await(
+        self.#api.listServiceVersions(options.serviceId, options.signal),
+      );
+      const detailResults = await Promise.all(
+        versions.map((v) => self.#api.getVersion(v.id, options.signal)),
+      );
+      const details: VersionDetailData[] = [];
+      for (const result of detailResults) {
+        if (result.isErr()) {
+          // listServiceVersions returns versions that have previously been deleted
+          // and can't be fetched using getVersion so we need to filter those out.
+          if (ApiError.is(result.error) && result.error.statusCode === 404)
+            continue;
+          return result;
+        }
+        details.push(result.value);
+      }
+      return Result.ok(
+        details.map(
+          (v): VersionInfo => ({
+            id: v.id,
+            status: v.status,
+            createdAt: v.createdAt,
+            previewDomain: v.previewDomain,
+          }),
+        ),
+      );
+    });
+  }
+
+  async showVersion(
+    options: ShowVersionOptions,
+  ): Promise<Result<VersionDetail, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      const v = yield* Result.await(
+        self.#api.getVersion(options.versionId, options.signal),
+      );
+      return Result.ok({
+        id: v.id,
+        status: v.status,
+        createdAt: v.createdAt,
+        previewDomain: v.previewDomain,
+        envVars: v.envVars ?? undefined,
+      });
+    });
+  }
+
+  async startVersion(
+    options: StartVersionOptions,
+  ): Promise<Result<void, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      yield* Result.await(
+        self.#api.startVersion(options.versionId, options.signal),
+      );
+      return Result.ok();
+    });
+  }
+
+  async stopVersion(
+    options: StopVersionOptions,
+  ): Promise<Result<void, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      yield* Result.await(
+        self.#api.stopVersion(options.versionId, options.signal),
+      );
+      return Result.ok();
+    });
+  }
+
+  async deleteVersion(
+    options: DeleteVersionOptions,
+  ): Promise<Result<void, ComputeError>> {
+    const self = this;
+    return Result.gen(async function* () {
+      yield* self.#checkAborted(options.signal);
+      yield* Result.await(
+        self.#api.deleteVersion(options.versionId, options.signal),
+      );
+      return Result.ok();
+    });
+  }
+
+  #checkAborted(signal?: AbortSignal): Result<void, CancelledError> {
+    if (signal?.aborted) {
+      return Result.err(new CancelledError());
+    }
+    return Result.ok(undefined);
+  }
+
+  async #resolveDeployTarget(options: {
+    projectId?: string;
+    serviceId?: string;
+    serviceName?: string;
+    region?: string;
+    signal?: AbortSignal;
+    interaction?: DeployInteraction;
+  }): Promise<
+    Result<
+      {
+        projectId: string;
+        serviceId: string;
+        serviceName: string;
+        region: string;
+      },
+      CancelledError | MissingArgumentError | ComputeError
+    >
+  > {
+    const self = this;
+    return Result.gen(async function* () {
+      if (options.serviceId) {
+        const service = yield* Result.await(
+          self.#api.getService(options.serviceId, options.signal),
+        );
+        const projectId = options.projectId ?? service.projectId;
+        if (!projectId) {
+          return Result.err(new MissingArgumentError({ field: "projectId" }));
+        }
+        return Result.ok({
+          projectId,
+          serviceId: service.id,
+          serviceName: service.name ?? service.id,
+          region: service.region.id,
+        });
+      }
+
+      let projectId = options.projectId;
+      if (!projectId) {
+        const projects = yield* Result.await(
+          self.#api.listProjects(options.signal),
+        );
+        const projectInfos = projects.map(
+          (p): ProjectInfo => ({
+            id: p.id,
+            name: p.name,
+            defaultRegion: p.defaultRegion ?? undefined,
+          }),
+        );
+
+        if (!options.interaction?.selectProject) {
+          return Result.err(new MissingArgumentError({ field: "projectId" }));
+        }
+
+        projectId = await options.interaction.selectProject(projectInfos);
+      }
+
+      if (options.serviceName && options.region) {
+        const response = yield* Result.await(
+          self.#api.createProjectService(
+            projectId,
+            {
+              displayName: options.serviceName,
+              regionId: options.region,
+            },
+            options.signal,
+          ),
+        );
+        return Result.ok({
+          projectId,
+          serviceId: response.id,
+          serviceName: response.name,
+          region: response.region.id,
+        });
+      }
+
+      const services = yield* Result.await(
+        self.#api.listProjectServices(projectId, options.signal),
+      );
+      const serviceInfos = services.map(
+        (s): ServiceInfo => ({
+          id: s.id,
+          name: s.name,
+          region: s.region.id,
+          projectId: s.projectId,
+        }),
+      );
+
+      if (!options.interaction?.selectService) {
+        return Result.err(new MissingArgumentError({ field: "serviceId" }));
+      }
+
+      const selectedServiceId =
+        await options.interaction.selectService(serviceInfos);
+
+      if (selectedServiceId !== null) {
+        const service = services.find((s) => s.id === selectedServiceId);
+        if (!service) {
+          throw new Error("selectService returned service ID not in the list");
+        }
+        return Result.ok({
+          projectId,
+          serviceId: selectedServiceId,
+          serviceName: service.name,
+          region: service.region.id,
+        });
+      }
+
+      let serviceName = options.serviceName;
+      if (!serviceName) {
+        if (!options.interaction?.provideServiceName) {
+          return Result.err(new MissingArgumentError({ field: "serviceName" }));
+        }
+        serviceName = await options.interaction.provideServiceName();
+      }
+
+      let region = options.region;
+      if (!region) {
+        if (!options.interaction?.selectRegion) {
+          return Result.err(new MissingArgumentError({ field: "region" }));
+        }
+        region = await options.interaction.selectRegion(REGIONS);
+      }
+
+      const response = yield* Result.await(
+        self.#api.createProjectService(
+          projectId,
+          {
+            displayName: serviceName,
+            regionId: region,
+          },
+          options.signal,
+        ),
+      );
+
+      return Result.ok({
+        projectId,
+        serviceId: response.id,
+        serviceName: response.name,
+        region: response.region.id,
+      });
+    });
+  }
+
+  async #uploadArtifact(
+    url: string,
+    body: Uint8Array,
+  ): Promise<Result<void, ArtifactError>> {
+    return Result.tryPromise({
+      try: async () => {
+        const res = await fetch(url, {
+          method: "PUT",
+          headers: { "content-type": "application/gzip" },
+          body,
+        });
+
+        if (!res.ok) {
+          let message = `Artifact upload failed with HTTP ${res.status}`;
+          try {
+            const json = (await res.json()) as { error?: unknown };
+            if (typeof json.error === "string" && json.error.length > 0) {
+              message = `Artifact upload failed: ${json.error}`;
+            }
+          } catch {
+            // ignore body parse failures
+          }
+          throw new Error(message);
+        }
+      },
+      catch: (e) =>
+        new ArtifactError({
+          message: e instanceof Error ? e.message : String(e),
+          cause: e,
+        }),
+    });
+  }
+}
+
+/**
+ * Sort versions: running/provisioning first, then by createdAt descending.
+ */
+function versionSortComparator(a: VersionInfo, b: VersionInfo): number {
+  const statusPriority = (s: string) =>
+    s === "running" ? 0 : s === "provisioning" ? 1 : 2;
+  const aPriority = statusPriority(a.status);
+  const bPriority = statusPriority(b.status);
+  if (aPriority !== bPriority) return aPriority - bPriority;
+  return b.createdAt.localeCompare(a.createdAt);
+}