otavia 0.1.0

package/src/deploy/s3.ts

@@ -0,0 +1,57 @@
+import type { CfnFragment } from "./types.js";
+import { toPascalCase } from "./types.js";
+
+/**
+ * Generate S3 bucket fragment (data bucket).
+ * AWS::S3::Bucket with PublicAccessBlock.
+ */
+export function generateBucket(bucketKey: string, bucketName: string): CfnFragment {
+  const logicalId = `${toPascalCase(bucketKey)}Bucket`;
+  return {
+    Resources: {
+      [logicalId]: {
+        Type: "AWS::S3::Bucket",
+        Properties: {
+          BucketName: bucketName,
+          PublicAccessBlockConfiguration: {
+            BlockPublicAcls: true,
+            BlockPublicPolicy: true,
+            IgnorePublicAcls: true,
+            RestrictPublicBuckets: true,
+          },
+        },
+      },
+    },
+    Outputs: {
+      [`${logicalId}Name`]: { Value: { Ref: logicalId } },
+      [`${logicalId}Arn`]: { Value: { "Fn::GetAtt": [logicalId, "Arn"] } },
+    },
+  };
+}
+
+/**
+ * Generate frontend asset bucket (single per stack).
+ * Same structure: AWS::S3::Bucket + PublicAccessBlock.
+ */
+export function generateFrontendBucket(bucketName: string): CfnFragment {
+  return {
+    Resources: {
+      FrontendBucket: {
+        Type: "AWS::S3::Bucket",
+        Properties: {
+          BucketName: bucketName,
+          PublicAccessBlockConfiguration: {
+            BlockPublicAcls: true,
+            BlockPublicPolicy: true,
+            IgnorePublicAcls: true,
+            RestrictPublicBuckets: true,
+          },
+        },
+      },
+    },
+    Outputs: {
+      FrontendBucketName: { Value: { Ref: "FrontendBucket" } },
+      FrontendBucketArn: { Value: { "Fn::GetAtt": ["FrontendBucket", "Arn"] } },
+    },
+  };
+}

package/src/deploy/template.ts

@@ -0,0 +1,264 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { stringify } from "yaml";
+import type { OtaviaYaml } from "../config/otavia-yaml-schema.js";
+import type { CellConfig } from "../config/cell-yaml-schema.js";
+import { loadOtaviaYaml } from "../config/load-otavia-yaml.js";
+import { loadCellConfig } from "../config/load-cell-yaml.js";
+import { resolveCellDir } from "../config/resolve-cell-dir.js";
+import { assertDeclaredParamsProvided, mergeParams, resolveParams } from "../config/resolve-params.js";
+import { loadEnvForCell } from "../utils/env.js";
+import { tablePhysicalName, bucketPhysicalName } from "../config/resource-names.js";
+import { generateDynamoDBTable } from "./dynamodb.js";
+import { generateBucket, generateFrontendBucket } from "./s3.js";
+import { generateLambdaFragment } from "./lambda.js";
+import { generateHttpApi } from "./api-gateway.js";
+import { generateCloudFrontDistribution } from "./cloudfront.js";
+import type { CfnFragment } from "./types.js";
+import { toPascalCase } from "./types.js";
+
+/** Build ref map: short logical id -> prefixed logical id for a cell's fragments */
+function buildRefMap(fragments: CfnFragment[], prefix: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const f of fragments) {
+    for (const key of Object.keys(f.Resources)) {
+      map.set(key, prefix + key);
+    }
+  }
+  return map;
+}
+
+/** Deep-replace Ref and Fn::GetAtt in a value using refMap */
+function replaceRefsInValue(val: unknown, refMap: Map<string, string>): unknown {
+  if (val === null || val === undefined) return val;
+  if (Array.isArray(val)) {
+    return val.map((item) => replaceRefsInValue(item, refMap));
+  }
+  if (typeof val === "object") {
+    const obj = val as Record<string, unknown>;
+    if ("Ref" in obj && typeof obj.Ref === "string" && refMap.has(obj.Ref)) {
+      return { Ref: refMap.get(obj.Ref) };
+    }
+    if ("Fn::GetAtt" in obj && Array.isArray(obj["Fn::GetAtt"])) {
+      const att = obj["Fn::GetAtt"] as string[];
+      if (att.length >= 1 && typeof att[0] === "string" && refMap.has(att[0])) {
+        return { "Fn::GetAtt": [refMap.get(att[0]), ...att.slice(1)] };
+      }
+    }
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = replaceRefsInValue(v, refMap);
+    }
+    return out;
+  }
+  return val;
+}
+
+/** Prefix fragment keys and rewrite internal Ref/GetAtt to use prefixed names */
+function prefixFragment(
+  fragment: CfnFragment,
+  prefix: string,
+  refMap: Map<string, string>
+): CfnFragment {
+  const prefixKey = (key: string) => prefix + key;
+  const resources: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fragment.Resources)) {
+    resources[prefixKey(key)] = replaceRefsInValue(value, refMap);
+  }
+  const result: CfnFragment = { Resources: resources };
+  if (fragment.Outputs) {
+    result.Outputs = {};
+    for (const [key, value] of Object.entries(fragment.Outputs)) {
+      result.Outputs[prefixKey(key)] = replaceRefsInValue(value, refMap);
+    }
+  }
+  if (fragment.Conditions) {
+    result.Conditions = {};
+    for (const [key, value] of Object.entries(fragment.Conditions)) {
+      result.Conditions[prefixKey(key)] = replaceRefsInValue(value, refMap);
+    }
+  }
+  return result;
+}
+
+function resolvedParamsToEnv(resolved: Record<string, string | unknown>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(resolved)) {
+    if (value === null || value === undefined) {
+      env[key] = "";
+    } else if (typeof value === "object") {
+      env[key] = JSON.stringify(value);
+    } else {
+      env[key] = String(value);
+    }
+  }
+  return env;
+}
+
+function toResourceEnvKey(prefix: string, key: string): string {
+  const normalized = key.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+  return `${prefix}${normalized}`;
+}
+function toApiPathPattern(mount: string, route: string): string {
+  const trimmedRoute = route.trim();
+  const mountPrefix = `/${mount}`.replace(/\/+/g, "/");
+  const joined = `${mountPrefix}${trimmedRoute.startsWith("/") ? trimmedRoute : `/${trimmedRoute}`}`;
+  return joined.replace(/\/+/g, "/");
+}
+
+/**
+ * Generate a single CloudFormation template (YAML) from OtaviaYaml + all cell configs + resolved params (cloud stage).
+ * Resources: each cell's tables -> DynamoDB, buckets -> S3, backend entries -> Lambda + API Gateway HTTP API,
+ * frontend -> single S3 bucket + CloudFront path behaviors for single domain.
+ */
+export function generateTemplate(rootDir: string, opts?: { certificateArn?: string }): string {
+  const otavia = loadOtaviaYaml(rootDir);
+  const stackName = otavia.stackName;
+  const domainHost = otavia.domain?.host ?? "";
+  const bucketSuffix =
+    domainHost.replace(/\./g, "-").toLowerCase().replace(/[^a-z0-9-]/g, "-") || "platform";
+  const frontendBucketName = `frontend-${stackName}-${bucketSuffix}`.toLowerCase();
+
+  const resources: Record<string, unknown> = {};
+  const outputs: Record<string, unknown> = {};
+  const conditions: Record<string, unknown> = {};
+  const pathBehaviors: Array<{ pathPattern: string; originId: string; isApi?: boolean }> = [];
+  const firstMount = otavia.cellsList[0]?.mount ?? "";
+  const defaultCellMount = otavia.defaultCell ?? firstMount;
+  const origin = domainHost ? `https://${domainHost}` : "";
+
+  for (const cellEntry of otavia.cellsList) {
+    const cellDir = resolveCellDir(rootDir, cellEntry.package);
+    if (!existsSync(resolve(cellDir, "cell.yaml"))) {
+      continue;
+    }
+    const config = loadCellConfig(cellDir);
+    const envMap = loadEnvForCell(rootDir, cellDir, { stage: "deploy" });
+    const merged = mergeParams(otavia.params, cellEntry.params) as Record<string, unknown>;
+    assertDeclaredParamsProvided(config.params, merged, cellEntry.mount);
+    const resolved = resolveParams(merged, envMap, { onMissingParam: "throw" });
+    const envVars = resolvedParamsToEnv(resolved);
+    const pathPrefix = `/${cellEntry.mount}`;
+    envVars.CELL_BASE_URL = origin ? `${origin}${pathPrefix}` : "";
+    if (firstMount) {
+      envVars.SSO_BASE_URL = origin ? `${origin}/${firstMount}` : "";
+    }
+    envVars.CELL_STAGE = "cloud";
+
+    const prefix = toPascalCase(cellEntry.mount);
+
+    if (config.tables) {
+      for (const [tableKey, tableConfig] of Object.entries(config.tables)) {
+        const tableName = tablePhysicalName(stackName, cellEntry.mount, tableKey);
+        const frag = generateDynamoDBTable(tableName, tableKey, tableConfig);
+        const refMap = buildRefMap([frag], prefix);
+        const prefixed = prefixFragment(frag, prefix, refMap);
+        Object.assign(resources, prefixed.Resources);
+        if (prefixed.Outputs) Object.assign(outputs, prefixed.Outputs);
+      }
+    }
+
+    if (config.buckets) {
+      for (const [bucketKey] of Object.entries(config.buckets)) {
+        const bucketName = bucketPhysicalName(stackName, cellEntry.mount, bucketKey);
+        const frag = generateBucket(bucketKey, bucketName);
+        const refMap = buildRefMap([frag], prefix);
+        const prefixed = prefixFragment(frag, prefix, refMap);
+        Object.assign(resources, prefixed.Resources);
+        if (prefixed.Outputs) Object.assign(outputs, prefixed.Outputs);
+      }
+    }
+
+    if (config.backend) {
+      const tableLogicalIds = config.tables
+        ? Object.keys(config.tables).map((k) => `${prefix}${toPascalCase(k)}Table`)
+        : [];
+      const bucketLogicalIds = config.buckets
+        ? Object.keys(config.buckets).map((k) => `${prefix}${toPascalCase(k)}Bucket`)
+        : [];
+      if (config.tables) {
+        for (const tableKey of Object.keys(config.tables)) {
+          envVars[toResourceEnvKey("DYNAMODB_TABLE_", tableKey)] = tablePhysicalName(
+            stackName,
+            cellEntry.mount,
+            tableKey
+          );
+        }
+      }
+      if (config.buckets) {
+        for (const bucketKey of Object.keys(config.buckets)) {
+          envVars[toResourceEnvKey("S3_BUCKET_", bucketKey)] = bucketPhysicalName(
+            stackName,
+            cellEntry.mount,
+            bucketKey
+          );
+        }
+      }
+      const apiRoutes: Array<{ functionLogicalId: string }> = [];
+      const apiPathPatterns = new Set<string>();
+
+      for (const [entryKey, entry] of Object.entries(config.backend.entries)) {
+        const frag = generateLambdaFragment(entryKey, prefix, {
+          handlerPath: `build/${cellEntry.mount}/${entryKey}/code.zip`,
+          runtime: config.backend.runtime,
+          timeout: entry.timeout,
+          memory: entry.memory,
+          envVars,
+          tableLogicalIds: tableLogicalIds.length > 0 ? tableLogicalIds : undefined,
+          bucketLogicalIds: bucketLogicalIds.length > 0 ? bucketLogicalIds : undefined,
+        });
+        Object.assign(resources, frag.Resources);
+        const funcLogicalId = `${prefix}${toPascalCase(entryKey)}Function`;
+        apiRoutes.push({ functionLogicalId: funcLogicalId });
+        for (const route of entry.routes ?? []) {
+          apiPathPatterns.add(toApiPathPattern(cellEntry.mount, route));
+        }
+      }
+
+      const apiFrag = generateHttpApi(prefix, `${stackName}-${cellEntry.mount}-api`, apiRoutes);
+      Object.assign(resources, apiFrag.Resources);
+      if (apiFrag.Outputs) Object.assign(outputs, apiFrag.Outputs);
+
+      if (apiPathPatterns.size === 0) {
+        apiPathPatterns.add(pathPrefix.endsWith("/") ? `${pathPrefix}*` : `${pathPrefix}/*`);
+      }
+      for (const pathPattern of Array.from(apiPathPatterns).sort((a, b) => b.length - a.length)) {
+        pathBehaviors.push({
+          pathPattern,
+          originId: `${prefix}HttpApi`,
+          isApi: true,
+        });
+      }
+    }
+  }
+
+  const frontendFrag = generateFrontendBucket(frontendBucketName);
+  Object.assign(resources, frontendFrag.Resources);
+  if (frontendFrag.Outputs) Object.assign(outputs, frontendFrag.Outputs);
+
+  const cloudFrontFrag = generateCloudFrontDistribution({
+    stackName,
+    domainHost,
+    defaultOriginId: "S3Frontend",
+    defaultCellMount,
+    frontendBucketRef: "FrontendBucket",
+    pathBehaviors: pathBehaviors.sort((a, b) => b.pathPattern.length - a.pathPattern.length),
+    hostedZoneId: otavia.domain?.dns?.provider === "cloudflare" ? undefined : otavia.domain?.dns?.zoneId,
+    certificateArn: opts?.certificateArn,
+  });
+  Object.assign(resources, cloudFrontFrag.Resources);
+  if (cloudFrontFrag.Outputs) Object.assign(outputs, cloudFrontFrag.Outputs);
+  if (cloudFrontFrag.Conditions) Object.assign(conditions, cloudFrontFrag.Conditions);
+
+  const template: Record<string, unknown> = {
+    AWSTemplateFormatVersion: "2010-09-09",
+    Description: `Otavia stack ${stackName}: single CloudFormation`,
+    Resources: resources,
+    Outputs: outputs,
+  };
+  if (Object.keys(conditions).length > 0) {
+    template.Conditions = conditions;
+  }
+
+  return stringify(template);
+}

package/src/deploy/types.ts

@@ -0,0 +1,16 @@
+/**
+ * CloudFormation fragment types for Otavia deploy.
+ */
+
+export type CfnFragment = {
+  Resources: Record<string, unknown>;
+  Outputs?: Record<string, unknown>;
+  Conditions?: Record<string, unknown>;
+};
+
+export function toPascalCase(s: string): string {
+  return s
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}

package/src/local/docker.ts

@@ -0,0 +1,175 @@
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export async function exec(cmd: string[], opts?: { cwd?: string }): Promise<ExecResult> {
+  const proc = Bun.spawn(cmd, {
+    cwd: opts?.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+
+  return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+export async function isDockerRunning(): Promise<boolean> {
+  const { exitCode } = await exec(["docker", "info"]);
+  return exitCode === 0;
+}
+
+export async function isContainerRunning(name: string): Promise<boolean> {
+  const { exitCode, stdout } = await exec(["docker", "inspect", "-f", "{{.State.Running}}", name]);
+  return exitCode === 0 && stdout === "true";
+}
+
+export async function containerExists(name: string): Promise<boolean> {
+  const { exitCode } = await exec(["docker", "inspect", name]);
+  return exitCode === 0;
+}
+
+export async function stopContainer(name: string): Promise<void> {
+  await exec(["docker", "rm", "-f", name]);
+}
+
+export async function getContainerHostPort(
+  name: string,
+  containerPort: number
+): Promise<number | undefined> {
+  const { exitCode, stdout } = await exec(["docker", "port", name, `${containerPort}/tcp`]);
+  if (exitCode !== 0 || !stdout) return undefined;
+  const firstLine = stdout.split(/\r?\n/)[0]?.trim();
+  if (!firstLine) return undefined;
+  const match = firstLine.match(/:(\d+)$/);
+  if (!match) return undefined;
+  const port = Number.parseInt(match[1], 10);
+  if (!Number.isFinite(port)) return undefined;
+  return port;
+}
+
+export interface DynamoDBOpts {
+  port: number;
+  persistent: boolean;
+  containerName: string;
+}
+
+export function buildDynamoDBArgs(opts: DynamoDBOpts): string[] {
+  const args = [
+    "docker",
+    "run",
+    "-d",
+    ...(opts.persistent ? [] : ["--rm"]),
+    "--name",
+    opts.containerName,
+    "-p",
+    `${opts.port}:8000`,
+    "amazon/dynamodb-local",
+    "-jar",
+    "DynamoDBLocal.jar",
+    "-sharedDb",
+  ];
+  if (!opts.persistent) {
+    args.push("-inMemory");
+  }
+  return args;
+}
+
+export async function startDynamoDB(opts: DynamoDBOpts): Promise<void> {
+  if (await isContainerRunning(opts.containerName)) {
+    const mappedPort = await getContainerHostPort(opts.containerName, 8000);
+    if (mappedPort === opts.port) return;
+    await stopContainer(opts.containerName);
+  }
+  if (await containerExists(opts.containerName)) {
+    await exec(["docker", "start", opts.containerName]);
+    const mappedPort = await getContainerHostPort(opts.containerName, 8000);
+    if (mappedPort === opts.port) return;
+    await stopContainer(opts.containerName);
+  }
+  const args = buildDynamoDBArgs(opts);
+  const { exitCode, stderr } = await exec(args);
+  if (exitCode !== 0) {
+    throw new Error(`Failed to start DynamoDB container: ${stderr}`);
+  }
+}
+
+export interface MinIOOpts {
+  port: number;
+  containerName: string;
+  dataDir?: string;
+  /** When true, add --rm so container is removed on exit (e.g. for e2e). */
+  rm?: boolean;
+}
+
+export function buildMinIOArgs(opts: MinIOOpts): string[] {
+  const args = [
+    "docker",
+    "run",
+    "-d",
+    ...(opts.rm ? ["--rm"] : []),
+    "--name",
+    opts.containerName,
+    "-p",
+    `${opts.port}:9000`,
+    "-e",
+    "MINIO_ROOT_USER=minioadmin",
+    "-e",
+    "MINIO_ROOT_PASSWORD=minioadmin",
+  ];
+  if (opts.dataDir) {
+    args.push("-v", `${opts.dataDir}:/data`);
+  }
+  args.push("minio/minio", "server", "/data");
+  return args;
+}
+
+export async function startMinIO(opts: MinIOOpts): Promise<void> {
+  if (await isContainerRunning(opts.containerName)) {
+    const mappedPort = await getContainerHostPort(opts.containerName, 9000);
+    if (mappedPort === opts.port) return;
+    await stopContainer(opts.containerName);
+  }
+  if (await containerExists(opts.containerName)) {
+    await exec(["docker", "start", opts.containerName]);
+    const mappedPort = await getContainerHostPort(opts.containerName, 9000);
+    if (mappedPort === opts.port) return;
+    await stopContainer(opts.containerName);
+  }
+  const args = buildMinIOArgs(opts);
+  const { exitCode, stderr } = await exec(args);
+  if (exitCode !== 0) {
+    throw new Error(`Failed to start MinIO container: ${stderr}`);
+  }
+}
+
+export async function waitForPort(port: number, timeoutMs = 30_000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const socket = await Bun.connect({
+        hostname: "127.0.0.1",
+        port,
+        socket: {
+          data() {},
+          open(socket) {
+            socket.end();
+          },
+          error() {},
+          close() {},
+        },
+      });
+      socket.end();
+      return true;
+    } catch {
+      await Bun.sleep(200);
+    }
+  }
+  return false;
+}

package/src/local/dynamodb-local.ts

@@ -0,0 +1,124 @@
+import {
+  type AttributeDefinition,
+  CreateTableCommand,
+  type CreateTableCommandInput,
+  DynamoDBClient,
+  type GlobalSecondaryIndex,
+  type KeySchemaElement,
+  ListTablesCommand,
+} from "@aws-sdk/client-dynamodb";
+import type { TableConfig } from "../config/cell-yaml-schema.js";
+
+function attrType(t: string): "S" | "N" | "B" {
+  const upper = t.toUpperCase();
+  if (upper === "S" || upper === "N" || upper === "B") return upper;
+  return "S";
+}
+
+export function buildCreateTableInput(
+  tableName: string,
+  config: TableConfig
+): CreateTableCommandInput {
+  const keyEntries = Object.entries(config.keys);
+  const keySchema: KeySchemaElement[] = keyEntries.map(([name], i) => ({
+    AttributeName: name,
+    KeyType: i === 0 ? "HASH" : "RANGE",
+  }));
+
+  const attrSet = new Map<string, string>();
+  for (const [name, type] of keyEntries) {
+    attrSet.set(name, attrType(type));
+  }
+
+  const gsiList: GlobalSecondaryIndex[] = [];
+  if (config.gsi) {
+    for (const [gsiName, gsiConfig] of Object.entries(config.gsi)) {
+      const gsiKeyEntries = Object.entries(gsiConfig.keys);
+      const gsiKeySchema: KeySchemaElement[] = gsiKeyEntries.map(([name], i) => ({
+        AttributeName: name,
+        KeyType: i === 0 ? "HASH" : "RANGE",
+      }));
+
+      for (const [name, type] of gsiKeyEntries) {
+        attrSet.set(name, attrType(type));
+      }
+
+      gsiList.push({
+        IndexName: gsiName,
+        KeySchema: gsiKeySchema,
+        Projection: {
+          ProjectionType: (gsiConfig.projection?.toUpperCase() as "ALL" | "KEYS_ONLY") || "ALL",
+        },
+      });
+    }
+  }
+
+  const attributeDefinitions: AttributeDefinition[] = [...attrSet.entries()].map(
+    ([name, type]) => ({
+      AttributeName: name,
+      AttributeType: type as "S" | "N" | "B",
+    })
+  );
+
+  const input: CreateTableCommandInput = {
+    TableName: tableName,
+    KeySchema: keySchema,
+    AttributeDefinitions: attributeDefinitions,
+    BillingMode: "PAY_PER_REQUEST",
+  };
+
+  if (gsiList.length > 0) {
+    input.GlobalSecondaryIndexes = gsiList;
+  }
+
+  return input;
+}
+
+function makeClient(endpoint: string): DynamoDBClient {
+  return new DynamoDBClient({
+    endpoint,
+    region: "local",
+    credentials: {
+      accessKeyId: "local",
+      secretAccessKey: "local",
+    },
+  });
+}
+
+export async function isDynamoDBReady(endpoint: string): Promise<boolean> {
+  const client = makeClient(endpoint);
+  try {
+    await client.send(new ListTablesCommand({}));
+    return true;
+  } catch {
+    return false;
+  } finally {
+    client.destroy();
+  }
+}
+
+export interface LocalTableEntry {
+  tableName: string;
+  config: TableConfig;
+}
+
+export async function ensureLocalTables(
+  endpoint: string,
+  tables: LocalTableEntry[]
+): Promise<void> {
+  const client = makeClient(endpoint);
+  try {
+    for (const table of tables) {
+      const input = buildCreateTableInput(table.tableName, table.config);
+      try {
+        await client.send(new CreateTableCommand(input));
+      } catch (err: unknown) {
+        const e = err as { name?: string };
+        if (e.name === "ResourceInUseException") continue;
+        throw err;
+      }
+    }
+  } finally {
+    client.destroy();
+  }
+}

package/src/local/minio-local.ts

@@ -0,0 +1,44 @@
+import { CreateBucketCommand, ListBucketsCommand, S3Client } from "@aws-sdk/client-s3";
+
+function makeClient(endpoint: string): S3Client {
+  return new S3Client({
+    endpoint,
+    region: "local",
+    forcePathStyle: true,
+    credentials: {
+      accessKeyId: "minioadmin",
+      secretAccessKey: "minioadmin",
+    },
+  });
+}
+
+export async function ensureLocalBuckets(endpoint: string, bucketNames: string[]): Promise<void> {
+  const client = makeClient(endpoint);
+  try {
+    for (const bucket of bucketNames) {
+      try {
+        await client.send(new CreateBucketCommand({ Bucket: bucket }));
+      } catch (err: unknown) {
+        const e = err as { name?: string };
+        if (e.name === "BucketAlreadyOwnedByYou" || e.name === "BucketAlreadyExists") {
+          continue;
+        }
+        throw err;
+      }
+    }
+  } finally {
+    client.destroy();
+  }
+}
+
+export async function isMinIOReady(endpoint: string): Promise<boolean> {
+  const client = makeClient(endpoint);
+  try {
+    await client.send(new ListBucketsCommand({}));
+    return true;
+  } catch {
+    return false;
+  } finally {
+    client.destroy();
+  }
+}