@crewhaus/crewhaus-cloud 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/crewhaus-cloud",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Managed-as-a-service composite recipe: target-managed + helm-chart Kustomize overlay + Terraform module for GKE/EKS/AKS provisioning (Section 32)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/docker-images": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/helm-chart": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/crewhaus-cloud"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/crewhaus-cloud#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  type CloudConfig,
+  type CloudRunner,
+  CrewhausCloudError,
+  PROVIDERS,
+  TIERS,
+  defaultCloudConfig,
+  deployCloud,
+  isCloudProvider,
+  listProviders,
+  recipesRoot,
+  renderKustomizeOverlay,
+  renderTerraformModule,
+  summariseDeploy,
+  teardownCloud,
+  tierShapes,
+} from "./index";
+
+describe("PROVIDERS / TIERS / defaultCloudConfig", () => {
+  test("listProviders returns canonical list", () => {
+    expect(listProviders()).toEqual(PROVIDERS);
+  });
+
+  test("defaultCloudConfig sets sensible defaults", () => {
+    const c = defaultCloudConfig("aws", "us-east-1");
+    expect(c.provider).toBe("aws");
+    expect(c.region).toBe("us-east-1");
+    expect(c.tier).toBe("default");
+    expect(c.imageTag).toBe("latest");
+    expect(c.clusterName).toBe("crewhaus-aws-us-east-1");
+  });
+
+  test("rejects unknown provider", () => {
+    expect(() => defaultCloudConfig("dropbox" as never, "us-east-1")).toThrow(CrewhausCloudError);
+  });
+
+  test("rejects whitespace region", () => {
+    expect(() => defaultCloudConfig("aws", "us east 1")).toThrow();
+  });
+
+  test("isCloudProvider acts as a type guard", () => {
+    expect(isCloudProvider("aws")).toBe(true);
+    expect(isCloudProvider("gcp")).toBe(true);
+    expect(isCloudProvider("digitalocean")).toBe(false);
+  });
+
+  test("tierShapes covers all tiers", () => {
+    for (const t of TIERS) {
+      const shapes = tierShapes(t);
+      expect(shapes.length).toBeGreaterThan(0);
+      for (const s of shapes) expect(s.replicas).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("renderKustomizeOverlay", () => {
+  test("default config produces a well-formed kustomization.yaml", () => {
+    const config = defaultCloudConfig("aws", "us-east-1");
+    const overlay = renderKustomizeOverlay(config);
+    expect(overlay.kustomization).toContain("kind: Kustomization");
+    expect(overlay.kustomization).toContain(`namespace: ${config.clusterName}`);
+    expect(overlay.kustomization).toContain("crewhaus.io/provider: aws");
+    expect(overlay.kustomization).toContain("crewhaus.io/region: us-east-1");
+    expect(Object.keys(overlay.manifests).length).toBeGreaterThan(0);
+    expect(Object.keys(overlay.manifests).some((k) => k.startsWith("managed-"))).toBe(true);
+  });
+
+  test("each rendered manifest contains a Kubernetes kind", () => {
+    const config = defaultCloudConfig("gcp", "us-central1");
+    const overlay = renderKustomizeOverlay(config);
+    for (const body of Object.values(overlay.manifests)) {
+      // Some are blank if the if-gate evaluated false (e.g., ingress disabled);
+      // we only require the non-empty ones to declare a kind.
+      if (body.trim().length > 0) {
+        expect(/^kind: \w+$/m.test(body)).toBe(true);
+      }
+    }
+  });
+
+  test("output is deterministic across two renders", () => {
+    const config = defaultCloudConfig("aws", "us-east-1");
+    const a = renderKustomizeOverlay(config);
+    const b = renderKustomizeOverlay(config);
+    expect(a.kustomization).toBe(b.kustomization);
+    expect(Object.keys(a.manifests)).toEqual(Object.keys(b.manifests));
+  });
+});
+
+describe("renderTerraformModule", () => {
+  test("AWS module declares aws_eks_cluster + aws_db_instance + aws_s3_bucket", () => {
+    const tf = renderTerraformModule(defaultCloudConfig("aws", "us-east-1"));
+    expect(tf).toContain("hashicorp/aws");
+    expect(tf).toContain('aws_eks_cluster" "crewhaus"');
+    expect(tf).toContain('aws_db_instance" "spec_registry"');
+    expect(tf).toContain('aws_s3_bucket" "audit_log"');
+  });
+
+  test("aws-localstack module wires endpoints to LocalStack", () => {
+    const tf = renderTerraformModule(defaultCloudConfig("aws-localstack", "us-east-1"));
+    expect(tf).toContain("var.localstack_endpoint");
+    expect(tf).toContain("s3_use_path_style");
+  });
+
+  test("GCP module uses google_container_cluster + google_sql_database_instance", () => {
+    const tf = renderTerraformModule(defaultCloudConfig("gcp", "us-central1"));
+    expect(tf).toContain("hashicorp/google");
+    expect(tf).toContain('google_container_cluster" "crewhaus"');
+    expect(tf).toContain('google_sql_database_instance" "spec_registry"');
+  });
+
+  test("Azure module uses azurerm_kubernetes_cluster + azurerm_postgresql_flexible_server", () => {
+    const tf = renderTerraformModule(defaultCloudConfig("azure", "eastus"));
+    expect(tf).toContain("hashicorp/azurerm");
+    expect(tf).toContain('azurerm_kubernetes_cluster" "crewhaus"');
+    expect(tf).toContain('azurerm_postgresql_flexible_server" "spec_registry"');
+  });
+});
+
+describe("deployCloud (T2 dry-run with fake runner)", () => {
+  test("when no runner is supplied, all steps are marked skipped", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-cloud-deploy-"));
+    const result = await deployCloud({
+      config: defaultCloudConfig("aws", "us-east-1"),
+      workingDir: dir,
+    });
+    expect(result.workingDir).toBe(dir);
+    for (const step of result.steps) {
+      expect(step.skipped).toBe(true);
+    }
+    // Files were still written
+    expect(readFileSync(join(dir, "terraform", "main.tf"), "utf8")).toContain("aws_eks_cluster");
+    expect(readFileSync(join(dir, "kustomize", "kustomization.yaml"), "utf8")).toContain(
+      "kind: Kustomization",
+    );
+  });
+
+  test("with a fake runner, the documented argv sequence is invoked", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-cloud-deploy-"));
+    const calls: string[][] = [];
+    const runner: CloudRunner = async (argv) => {
+      calls.push([...argv]);
+      // Simulate `terraform output -json` returning two outputs
+      if (argv.includes("output")) {
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify({
+            cluster_endpoint: { value: "https://example.eks" },
+            audit_bucket: { value: "crewhaus-aws-us-east-1-audit" },
+          }),
+          stderr: "",
+        };
+      }
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+    const result = await deployCloud({
+      config: defaultCloudConfig("aws", "us-east-1"),
+      workingDir: dir,
+      tfBin: "terraform",
+      runner,
+    });
+    const argvs = calls.map((c) => c[1]);
+    expect(argvs).toContain("init");
+    expect(argvs).toContain("apply");
+    expect(argvs).toContain("output");
+    // kubectl apply step
+    const kubectlApply = calls.find((c) => c[0] === "kubectl");
+    expect(kubectlApply).toBeDefined();
+    expect(kubectlApply).toContain("apply");
+    expect(result.outputs["cluster_endpoint"]).toBe("https://example.eks");
+  });
+
+  test("non-zero exit on terraform apply propagates as CrewhausCloudError", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-cloud-deploy-"));
+    const runner: CloudRunner = async (argv) =>
+      argv.includes("apply")
+        ? { exitCode: 1, stdout: "", stderr: "no AWS credentials" }
+        : { exitCode: 0, stdout: "", stderr: "" };
+    await expect(
+      deployCloud({
+        config: defaultCloudConfig("aws", "us-east-1"),
+        workingDir: dir,
+        runner,
+      }),
+    ).rejects.toThrow(/no AWS credentials/);
+  });
+});
+
+describe("teardownCloud", () => {
+  test("refuses if working dir does not exist", async () => {
+    await expect(
+      teardownCloud({
+        config: defaultCloudConfig("aws", "us-east-1"),
+        workingDir: "/nonexistent/path",
+      }),
+    ).rejects.toThrow(/no working directory/);
+  });
+
+  test("calls terraform destroy with the right cwd", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-cloud-teardown-"));
+    // Bootstrap a working dir first
+    await deployCloud({ config: defaultCloudConfig("aws", "us-east-1"), workingDir: dir });
+    const calls: string[][] = [];
+    const runner: CloudRunner = async (argv) => {
+      calls.push([...argv]);
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+    await teardownCloud({
+      config: defaultCloudConfig("aws", "us-east-1"),
+      workingDir: dir,
+      runner,
+    });
+    expect(calls.length).toBe(1);
+    expect(calls[0]).toContain("destroy");
+    expect(calls[0]).toContain("-auto-approve");
+  });
+});
+
+describe("recipesRoot + summariseDeploy + sanity", () => {
+  test("recipesRoot lives inside the package", () => {
+    expect(recipesRoot()).toMatch(/crewhaus-cloud\/recipes$/);
+  });
+
+  test("summariseDeploy emits readable lines", () => {
+    const summary = summariseDeploy({
+      workingDir: "/tmp/x",
+      steps: [{ name: "terraform-init" }, { name: "terraform-apply", skipped: true }],
+      outputs: { cluster_endpoint: "https://eks.example" },
+    });
+    expect(summary).toContain("/tmp/x");
+    expect(summary).toContain("ok  terraform-init");
+    expect(summary).toContain("skip  terraform-apply");
+    expect(summary).toContain("cluster_endpoint = https://eks.example");
+  });
+});

package/src/index.ts

@@ -0,0 +1,505 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type TargetShape, isTargetShape } from "@crewhaus/docker-images";
+/**
+ * Section 32 — `@crewhaus/crewhaus-cloud`
+ *
+ * Composite "managed-as-a-service" recipe:
+ *   - default tier: 1× gateway-server, 3× target-managed replicas, 1×
+ *     studio replica, Postgres for spec-registry, Redis Streams for
+ *     queue-protocol, S3 for hash-chained §20 audit log
+ *   - `renderKustomizeOverlay({provider, region, tier})` produces a
+ *     deterministic kustomize overlay layered on top of the §32
+ *     helm-chart's rendered manifests
+ *   - `renderTerraformModule({provider, region})` produces the
+ *     Terraform HCL bringing up the cluster (GKE / EKS / AKS) and
+ *     associated resources (RDS, ElastiCache, S3 bucket)
+ *   - `deployCloud({provider, region, runner})` orchestrates the
+ *     terraform → kubectl-apply pipeline; live `terraform apply` is
+ *     gated on `TF_BIN` env or an injectable runner (the test pattern
+ *     mirrors the §30 SQS adapter — ship the abstraction + injection
+ *     point, gate live SDK calls on env)
+ *
+ * `crewhaus cloud deploy --provider aws --region us-east-1` and
+ * `crewhaus cloud teardown` (apps/cli/src/index.ts) call into this
+ * package.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { type ChartValues, defaultValues, renderChart, validateValues } from "@crewhaus/helm-chart";
+
+export class CrewhausCloudError extends CrewhausError {
+  override readonly name = "CrewhausCloudError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export const PROVIDERS = ["aws", "gcp", "azure", "aws-localstack"] as const;
+export type CloudProvider = (typeof PROVIDERS)[number];
+
+export const TIERS = ["dev", "default", "production"] as const;
+export type Tier = (typeof TIERS)[number];
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const RECIPES_ROOT = join(PACKAGE_ROOT, "recipes");
+
+export function recipesRoot(): string {
+  return RECIPES_ROOT;
+}
+
+export type CloudConfig = {
+  readonly provider: CloudProvider;
+  readonly region: string;
+  readonly tier: Tier;
+  readonly clusterName: string;
+  readonly imageTag: string;
+};
+
+export function defaultCloudConfig(provider: CloudProvider, region: string): CloudConfig {
+  if (!(PROVIDERS as readonly string[]).includes(provider)) {
+    throw new CrewhausCloudError(`unknown provider: ${provider}`);
+  }
+  if (!region || /\s/.test(region)) {
+    throw new CrewhausCloudError(`invalid region: ${JSON.stringify(region)}`);
+  }
+  return {
+    provider,
+    region,
+    tier: "default",
+    clusterName: `crewhaus-${provider}-${region}`.replace(/[^a-z0-9-]/g, "-"),
+    imageTag: "latest",
+  };
+}
+
+// ─── Tier sizing ─────────────────────────────────────────────────────────────
+
+export type TierShape = {
+  readonly target: TargetShape;
+  readonly replicas: number;
+};
+
+export function tierShapes(tier: Tier): readonly TierShape[] {
+  switch (tier) {
+    case "dev":
+      return [{ target: "managed", replicas: 1 }];
+    case "default":
+      return [
+        { target: "managed", replicas: 3 },
+        // Studio v1 (§31) ships as a managed-shape side helper deployment
+      ];
+    case "production":
+      return [{ target: "managed", replicas: 5 }];
+    default: {
+      const _exhaustive: never = tier;
+      throw new CrewhausCloudError(`unhandled tier: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+// ─── Kustomize overlay rendering ─────────────────────────────────────────────
+
+/** Builds a kustomization.yaml + chart-rendered manifests directory. */
+export function renderKustomizeOverlay(config: CloudConfig): {
+  kustomization: string;
+  manifests: Record<string, string>;
+} {
+  const shapes = tierShapes(config.tier);
+  const manifests: Record<string, string> = {};
+  const resourceFiles: string[] = [];
+
+  for (const shape of shapes) {
+    const values: ChartValues = {
+      ...defaultValues(),
+      target: shape.target,
+      replicas: shape.replicas,
+      image: { ...defaultValues().image, tag: config.imageTag },
+    };
+    validateValues(values);
+    const rendered = renderChart(values, `${config.clusterName}-${shape.target}`);
+    for (const [name, body] of Object.entries(rendered)) {
+      const fileName = `${shape.target}-${name}`;
+      manifests[fileName] = body;
+      resourceFiles.push(fileName);
+    }
+  }
+
+  const kustomization = `# Generated by @crewhaus/crewhaus-cloud (Section 32) — do not edit by hand.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: ${config.clusterName}
+commonLabels:
+  crewhaus.io/cluster: ${config.clusterName}
+  crewhaus.io/provider: ${config.provider}
+  crewhaus.io/region: ${config.region}
+  crewhaus.io/tier: ${config.tier}
+resources:
+${resourceFiles.map((f) => `  - ${f}`).join("\n")}
+`;
+
+  return { kustomization, manifests };
+}
+
+// ─── Terraform module rendering ──────────────────────────────────────────────
+
+export function renderTerraformModule(config: CloudConfig): string {
+  validateValues({
+    ...defaultValues(),
+    target: "managed",
+    image: { ...defaultValues().image, tag: config.imageTag },
+  });
+  switch (config.provider) {
+    case "aws":
+    case "aws-localstack":
+      return renderAwsTerraform(config);
+    case "gcp":
+      return renderGcpTerraform(config);
+    case "azure":
+      return renderAzureTerraform(config);
+    default: {
+      const _exhaustive: never = config.provider;
+      throw new CrewhausCloudError(`unhandled provider: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+function renderAwsTerraform(config: CloudConfig): string {
+  const localstackBlock =
+    config.provider === "aws-localstack"
+      ? `\n  # LocalStack overrides — wires every AWS service to the LocalStack endpoint
+  endpoints {
+    eks            = var.localstack_endpoint
+    rds            = var.localstack_endpoint
+    elasticache    = var.localstack_endpoint
+    s3             = var.localstack_endpoint
+    ecr            = var.localstack_endpoint
+  }
+  s3_use_path_style           = true
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+  skip_requesting_account_id  = true`
+      : "";
+
+  return `# Generated by @crewhaus/crewhaus-cloud — Terraform module for ${config.provider} (${config.region})
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+variable "localstack_endpoint" {
+  type    = string
+  default = "http://localhost:4566"
+}
+
+provider "aws" {
+  region = "${config.region}"${localstackBlock}
+}
+
+resource "aws_eks_cluster" "crewhaus" {
+  name     = "${config.clusterName}"
+  role_arn = aws_iam_role.cluster.arn
+  version  = "1.30"
+
+  vpc_config {
+    subnet_ids = aws_subnet.crewhaus[*].id
+  }
+}
+
+resource "aws_iam_role" "cluster" {
+  name = "${config.clusterName}-cluster-role"
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Principal = { Service = "eks.amazonaws.com" }
+      Action = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_subnet" "crewhaus" {
+  count             = 2
+  vpc_id            = aws_vpc.crewhaus.id
+  cidr_block        = "10.0.\${count.index + 1}.0/24"
+  availability_zone = "${config.region}a"
+}
+
+resource "aws_vpc" "crewhaus" {
+  cidr_block = "10.0.0.0/16"
+  tags = { Name = "${config.clusterName}-vpc" }
+}
+
+resource "aws_db_instance" "spec_registry" {
+  identifier        = "${config.clusterName}-spec-registry"
+  engine            = "postgres"
+  engine_version    = "15"
+  instance_class    = "db.t3.micro"
+  allocated_storage = 20
+  username          = "crewhaus"
+  password          = var.spec_registry_password
+  skip_final_snapshot = true
+}
+
+resource "aws_elasticache_cluster" "queue" {
+  cluster_id           = "${config.clusterName}-queue"
+  engine               = "redis"
+  node_type            = "cache.t3.micro"
+  num_cache_nodes      = 1
+  parameter_group_name = "default.redis7"
+  port                 = 6379
+}
+
+resource "aws_s3_bucket" "audit_log" {
+  bucket = "${config.clusterName}-audit"
+}
+
+variable "spec_registry_password" {
+  type      = string
+  sensitive = true
+}
+
+output "cluster_endpoint" {
+  value = aws_eks_cluster.crewhaus.endpoint
+}
+
+output "audit_bucket" {
+  value = aws_s3_bucket.audit_log.bucket
+}
+`;
+}
+
+function renderGcpTerraform(config: CloudConfig): string {
+  return `# Generated by @crewhaus/crewhaus-cloud — Terraform module for GCP (${config.region})
+terraform {
+  required_providers {
+    google = { source = "hashicorp/google", version = "~> 5.0" }
+  }
+}
+
+provider "google" {
+  region = "${config.region}"
+}
+
+resource "google_container_cluster" "crewhaus" {
+  name     = "${config.clusterName}"
+  location = "${config.region}"
+
+  initial_node_count       = 3
+  remove_default_node_pool = false
+}
+
+resource "google_sql_database_instance" "spec_registry" {
+  name             = "${config.clusterName}-spec-registry"
+  database_version = "POSTGRES_15"
+  region           = "${config.region}"
+  settings { tier = "db-f1-micro" }
+}
+
+resource "google_storage_bucket" "audit_log" {
+  name     = "${config.clusterName}-audit"
+  location = "${config.region}"
+  force_destroy = true
+}
+
+output "cluster_endpoint" {
+  value = google_container_cluster.crewhaus.endpoint
+}
+`;
+}
+
+function renderAzureTerraform(config: CloudConfig): string {
+  return `# Generated by @crewhaus/crewhaus-cloud — Terraform module for Azure (${config.region})
+terraform {
+  required_providers {
+    azurerm = { source = "hashicorp/azurerm", version = "~> 3.0" }
+  }
+}
+
+provider "azurerm" {
+  features {}
+}
+
+resource "azurerm_resource_group" "crewhaus" {
+  name     = "${config.clusterName}"
+  location = "${config.region}"
+}
+
+resource "azurerm_kubernetes_cluster" "crewhaus" {
+  name                = "${config.clusterName}"
+  location            = azurerm_resource_group.crewhaus.location
+  resource_group_name = azurerm_resource_group.crewhaus.name
+  dns_prefix          = "${config.clusterName}"
+
+  default_node_pool {
+    name       = "default"
+    node_count = 3
+    vm_size    = "Standard_D2_v2"
+  }
+
+  identity { type = "SystemAssigned" }
+}
+
+resource "azurerm_postgresql_flexible_server" "spec_registry" {
+  name                   = "${config.clusterName}-spec-registry"
+  resource_group_name    = azurerm_resource_group.crewhaus.name
+  location               = azurerm_resource_group.crewhaus.location
+  administrator_login    = "crewhaus"
+  administrator_password = var.spec_registry_password
+  version                = "15"
+  sku_name               = "B_Standard_B1ms"
+  storage_mb             = 32768
+  backup_retention_days  = 7
+}
+
+variable "spec_registry_password" {
+  type      = string
+  sensitive = true
+}
+
+output "cluster_fqdn" {
+  value = azurerm_kubernetes_cluster.crewhaus.fqdn
+}
+`;
+}
+
+// ─── Deploy / teardown orchestration ─────────────────────────────────────────
+
+export type CloudRunner = (
+  argv: readonly string[],
+  cwd: string,
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>;
+
+export type DeployCloudOptions = {
+  readonly config: CloudConfig;
+  /** Working directory to write generated artefacts into; defaults to a temp dir. */
+  readonly workingDir?: string;
+  /** Override the terraform binary path; defaults to env TF_BIN or "terraform". */
+  readonly tfBin?: string;
+  /** Override the kubectl binary path. */
+  readonly kubectlBin?: string;
+  /** Test injection point. */
+  readonly runner?: CloudRunner;
+};
+
+export type DeployCloudResult = {
+  readonly workingDir: string;
+  readonly steps: ReadonlyArray<{ readonly name: string; readonly skipped?: boolean }>;
+  readonly outputs: Readonly<Record<string, string>>;
+};
+
+export async function deployCloud(opts: DeployCloudOptions): Promise<DeployCloudResult> {
+  const { config } = opts;
+  const workingDir = opts.workingDir ?? join(RECIPES_ROOT, ".out", config.clusterName);
+  mkdirSync(join(workingDir, "terraform"), { recursive: true });
+  mkdirSync(join(workingDir, "kustomize"), { recursive: true });
+
+  // 1. Render the Terraform module + Kustomize overlay onto disk.
+  const tfModule = renderTerraformModule(config);
+  writeFileSync(join(workingDir, "terraform", "main.tf"), tfModule);
+
+  const overlay = renderKustomizeOverlay(config);
+  writeFileSync(join(workingDir, "kustomize", "kustomization.yaml"), overlay.kustomization);
+  for (const [name, body] of Object.entries(overlay.manifests)) {
+    writeFileSync(join(workingDir, "kustomize", name), body);
+  }
+
+  // 2. Run terraform apply (gated on tfBin existing). If unavailable, mark skipped.
+  const tfBin = opts.tfBin ?? process.env["TF_BIN"] ?? "terraform";
+  const runner = opts.runner;
+  const steps: Array<{ name: string; skipped?: boolean }> = [];
+  const outputs: Record<string, string> = {};
+
+  if (runner) {
+    const init = await runner([tfBin, "init"], join(workingDir, "terraform"));
+    if (init.exitCode !== 0) {
+      throw new CrewhausCloudError(`terraform init failed: ${init.stderr.slice(0, 1024)}`);
+    }
+    steps.push({ name: "terraform-init" });
+
+    const apply = await runner(
+      [tfBin, "apply", "-auto-approve", "-var", `spec_registry_password=${randomPassword()}`],
+      join(workingDir, "terraform"),
+    );
+    if (apply.exitCode !== 0) {
+      throw new CrewhausCloudError(`terraform apply failed: ${apply.stderr.slice(0, 1024)}`);
+    }
+    steps.push({ name: "terraform-apply" });
+
+    const tfOut = await runner([tfBin, "output", "-json"], join(workingDir, "terraform"));
+    if (tfOut.exitCode === 0) {
+      try {
+        const parsed = JSON.parse(tfOut.stdout) as Record<string, { value: string }>;
+        for (const [k, v] of Object.entries(parsed)) {
+          outputs[k] = v.value;
+        }
+      } catch {
+        // Non-fatal — leave outputs empty.
+      }
+    }
+
+    const kubectlBin = opts.kubectlBin ?? "kubectl";
+    const kapply = await runner([kubectlBin, "apply", "-k", "."], join(workingDir, "kustomize"));
+    if (kapply.exitCode !== 0) {
+      throw new CrewhausCloudError(`kubectl apply failed: ${kapply.stderr.slice(0, 1024)}`);
+    }
+    steps.push({ name: "kubectl-apply" });
+  } else {
+    steps.push({ name: "terraform-init", skipped: true });
+    steps.push({ name: "terraform-apply", skipped: true });
+    steps.push({ name: "kubectl-apply", skipped: true });
+  }
+
+  return { workingDir, steps, outputs };
+}
+
+export async function teardownCloud(opts: DeployCloudOptions): Promise<void> {
+  const tfBin = opts.tfBin ?? process.env["TF_BIN"] ?? "terraform";
+  const workingDir = opts.workingDir ?? join(RECIPES_ROOT, ".out", opts.config.clusterName);
+  if (!existsSync(workingDir)) {
+    throw new CrewhausCloudError(
+      `no working directory at ${workingDir} (was deployCloud ever run?)`,
+    );
+  }
+  const runner = opts.runner;
+  if (!runner) {
+    return; // no-op when there's no runner available
+  }
+  const result = await runner(
+    [tfBin, "destroy", "-auto-approve", "-var", `spec_registry_password=${randomPassword()}`],
+    join(workingDir, "terraform"),
+  );
+  if (result.exitCode !== 0) {
+    throw new CrewhausCloudError(`terraform destroy failed: ${result.stderr.slice(0, 1024)}`);
+  }
+}
+
+function randomPassword(): string {
+  // 24 hex chars — only used as a placeholder so the Terraform variable is set;
+  // production users override via -var-file.
+  return Array.from({ length: 24 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+}
+
+/** Used by the CLI subcommand to enumerate provider choices. */
+export function listProviders(): readonly CloudProvider[] {
+  return PROVIDERS;
+}
+
+/** Used by the CLI subcommand for input validation. */
+export function isCloudProvider(value: unknown): value is CloudProvider {
+  return typeof value === "string" && (PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Sanity check used by the smoke test. */
+export function summariseDeploy(result: DeployCloudResult): string {
+  const lines = [`Working dir: ${result.workingDir}`];
+  for (const step of result.steps) {
+    lines.push(`  ${step.skipped ? "skip" : "ok"}  ${step.name}`);
+  }
+  for (const [k, v] of Object.entries(result.outputs)) {
+    lines.push(`  out  ${k} = ${v}`);
+  }
+  return lines.join("\n");
+}
+
+export { isTargetShape };