csrd-utils 0.3.7__tar.gz → 0.3.9__tar.gz

{csrd_utils-0.3.7 → csrd_utils-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.7
+Version: 0.3.9
 Summary: CLI utilities for csrd service generation and feature augmentation
 Project-URL: Repository, https://github.com/csrd-api/fastapi-common
 Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/utils
@@ -26,9 +26,11 @@ pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#sub
 ```bash
 csrd --help
 csrd --version
-csrd new service                                  # interactive prompts
+csrd new service                                  # compact interactive mode (prompts 1-6, then advanced gate)
 csrd new service --interactive --name items       # pre-fills name prompt with 'items'
 csrd new service --name inventory --no-interactive --output .
+csrd new cluster --spec ./cluster.yaml --output .
+csrd new cluster                                  # interactive cluster builder (preset + service prompts)
 csrd feature list
 csrd feature plan workers --service .
 csrd feature plan workers --service . --json
@@ -40,10 +42,14 @@ csrd doctor --service .
 
 ### Interactive generation behavior
 
-- `csrd new service` runs interactive prompts by default.
+- `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
+- In compact mode, advanced options are hidden by default.
+- `csrd new service --interactive` runs the full verbose interactive flow.
 - Passing `--name <value>` in interactive mode uses that value as the name prompt default.
 - You can still overwrite the default by entering a different value at the prompt.
 - Use `--no-interactive` for fully flag-driven generation.
+- Database default is `none`.
+- All yes/no prompts default to `No` (`y/N`).
 
 ## Typical workflow
 
@@ -96,6 +102,7 @@ If an agent can only see the installed CLI (not source files), use this explorat
 ```bash
 csrd --help
 csrd new --help
+csrd new cluster --help
 csrd feature --help
 csrd doctor --help
 csrd feature list

{csrd_utils-0.3.7 → csrd_utils-0.3.9}/README.md

@@ -13,9 +13,11 @@ pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#sub
 ```bash
 csrd --help
 csrd --version
-csrd new service                                  # interactive prompts
+csrd new service                                  # compact interactive mode (prompts 1-6, then advanced gate)
 csrd new service --interactive --name items       # pre-fills name prompt with 'items'
 csrd new service --name inventory --no-interactive --output .
+csrd new cluster --spec ./cluster.yaml --output .
+csrd new cluster                                  # interactive cluster builder (preset + service prompts)
 csrd feature list
 csrd feature plan workers --service .
 csrd feature plan workers --service . --json
@@ -27,10 +29,14 @@ csrd doctor --service .
 
 ### Interactive generation behavior
 
-- `csrd new service` runs interactive prompts by default.
+- `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
+- In compact mode, advanced options are hidden by default.
+- `csrd new service --interactive` runs the full verbose interactive flow.
 - Passing `--name <value>` in interactive mode uses that value as the name prompt default.
 - You can still overwrite the default by entering a different value at the prompt.
 - Use `--no-interactive` for fully flag-driven generation.
+- Database default is `none`.
+- All yes/no prompts default to `No` (`y/N`).
 
 ## Typical workflow
 
@@ -83,6 +89,7 @@ If an agent can only see the installed CLI (not source files), use this explorat
 ```bash
 csrd --help
 csrd new --help
+csrd new cluster --help
 csrd feature --help
 csrd doctor --help
 csrd feature list

{csrd_utils-0.3.7 → csrd_utils-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.3.7"
+version = "0.3.9"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"

{csrd_utils-0.3.7 → csrd_utils-0.3.9}/src/csrd_utils/__main__.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import TypedDict
 
 from .augmentor import ServiceAugmentor
+from .cluster import PRESETS, ClusterSpec, ServiceSpec, generate_cluster, load_cluster_spec
 from .doctor import run_doctor
 from .generator import generate_service
 from .resources import features_path
@@ -33,6 +34,12 @@ class GenerateServiceArgs(TypedDict):
     overwrite_if_exists: bool
 
 
+class GenerateClusterArgs(TypedDict):
+    spec: ClusterSpec
+    output_dir: Path
+    overwrite_if_exists: bool
+
+
 def _prompt_text(label: str, default: str) -> str:
     value = input(f"{label} [{default}]: ").strip()
     return value or default
@@ -70,6 +77,7 @@ def _prompt_int(label: str, default: int) -> int:
 
 def _collect_new_service_config(args: argparse.Namespace) -> GenerateServiceArgs:
     explicit_interactive = getattr(args, "interactive", None)
+    is_explicit_interactive = explicit_interactive is True
     interactive = (
         bool(explicit_interactive) if explicit_interactive is not None else args.name is None
     )
@@ -112,36 +120,51 @@ def _collect_new_service_config(args: argparse.Namespace) -> GenerateServiceArgs
         plural_default = f"{model_name.lower()}s"
     model_name_plural = _prompt_text("Model name plural", plural_default)
 
-    database = _prompt_choice("Database", ["sqlite", "maria", "postgres", "none"], args.database)
-    has_database = database != "none"
-    selected_database = "sqlite" if not has_database else database
-
-    has_delegates = _prompt_bool("Enable delegates", args.delegates)
-    upstreams_default = args.upstreams
-    if has_delegates and not upstreams_default:
-        upstreams_default = "http://service-a:8080"
-    upstreams = (
-        _prompt_text("Delegates upstreams (comma-separated)", upstreams_default)
-        if has_delegates
-        else ""
-    )
-
-    has_workers = _prompt_bool("Enable workers", args.workers)
-    broker = (
-        _prompt_choice("Worker broker", ["redis", "rabbitmq"], args.broker)
-        if has_workers
-        else args.broker
-    )
+    show_advanced = True
+    if not is_explicit_interactive:
+        show_advanced = _prompt_bool("Show advanced configuration options", False)
 
-    has_caching = _prompt_bool("Enable caching", args.caching)
-    cache_backend = (
-        _prompt_choice("Cache backend", ["redis"], args.cache_backend)
-        if has_caching
-        else args.cache_backend
-    )
+    if show_advanced:
+        database = _prompt_choice(
+            "Database", ["sqlite", "maria", "postgres", "none"], args.database
+        )
+        has_database = database != "none"
+        has_delegates = _prompt_bool("Enable delegates", False)
+        upstreams_default = args.upstreams
+        if has_delegates and not upstreams_default:
+            upstreams_default = "http://service-a:8080"
+        upstreams = (
+            _prompt_text("Delegates upstreams (comma-separated)", upstreams_default)
+            if has_delegates
+            else ""
+        )
+        has_workers = _prompt_bool("Enable workers", False)
+        broker = (
+            _prompt_choice("Worker broker", ["redis", "rabbitmq"], args.broker)
+            if has_workers
+            else args.broker
+        )
+        has_caching = _prompt_bool("Enable caching", False)
+        cache_backend = (
+            _prompt_choice("Cache backend", ["redis"], args.cache_backend)
+            if has_caching
+            else args.cache_backend
+        )
+        has_structured_logging = _prompt_bool("Enable structured logging", False)
+        overwrite_if_exists = _prompt_bool("Overwrite if target exists", False)
+    else:
+        database = args.database
+        has_database = database != "none"
+        has_delegates = args.delegates
+        upstreams = args.upstreams if has_delegates else ""
+        has_workers = args.workers
+        broker = args.broker
+        has_caching = args.caching
+        cache_backend = args.cache_backend
+        has_structured_logging = args.structured_logging
+        overwrite_if_exists = args.force
 
-    has_structured_logging = _prompt_bool("Enable structured logging", args.structured_logging)
-    overwrite_if_exists = _prompt_bool("Overwrite if target exists", args.force)
+    selected_database = "sqlite" if not has_database else database
 
     return GenerateServiceArgs(
         {
@@ -165,6 +188,72 @@ def _collect_new_service_config(args: argparse.Namespace) -> GenerateServiceArgs
     )
 
 
+def _collect_new_cluster_config(args: argparse.Namespace) -> GenerateClusterArgs:
+    if args.spec is not None:
+        return GenerateClusterArgs(
+            {
+                "spec": load_cluster_spec(args.spec),
+                "output_dir": args.output,
+                "overwrite_if_exists": args.force,
+            }
+        )
+
+    print("Interactive cluster mode: press Enter to accept defaults.")
+    cluster_name = _prompt_text("Cluster name", args.name or "my-cluster")
+    preset = _prompt_choice("Preset", list(PRESETS.keys()), args.preset)
+    services: list[ServiceSpec] = []
+
+    add_more = _prompt_bool("Add more services", False)
+    index = 1
+    default_port = 8091
+    while add_more:
+        print(f"Configuring service #{index}")
+        service_name = _prompt_text("Service name", f"service-{index}")
+        service_type = _prompt_choice(
+            "Service type", ["db", "delegate", "worker", "platform"], "db"
+        )
+        service: ServiceSpec = {
+            "name": service_name,
+            "type": service_type,
+            "port": _prompt_int("Service port", default_port),
+        }
+
+        if service_type == "db":
+            service["database"] = _prompt_choice(
+                "Database", ["sqlite", "maria", "postgres"], "sqlite"
+            )
+        elif service_type == "delegate":
+            delegates_raw = _prompt_text("Delegates (comma-separated)", "")
+            service["delegates"] = [
+                entry.strip() for entry in delegates_raw.split(",") if entry.strip()
+            ]
+        elif service_type == "worker":
+            service["broker"] = _prompt_choice("Broker", ["redis", "rabbitmq"], "redis")
+        else:
+            service["role"] = _prompt_text("Platform role", "custom")
+
+        requires_raw = _prompt_text("Requires (comma-separated)", "")
+        service["requires"] = [entry.strip() for entry in requires_raw.split(",") if entry.strip()]
+        features_raw = _prompt_text("Features (comma-separated)", "")
+        service["features"] = [entry.strip() for entry in features_raw.split(",") if entry.strip()]
+
+        services.append(service)
+        index += 1
+        default_port += 1
+        add_more = _prompt_bool("Add more services", False)
+
+    return GenerateClusterArgs(
+        {
+            "spec": {
+                "cluster": {"name": cluster_name, "preset": preset},
+                "services": services,
+            },
+            "output_dir": args.output,
+            "overwrite_if_exists": args.force,
+        }
+    )
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="csrd", description="csrd utilities")
     parser.add_argument(
@@ -207,7 +296,7 @@ def _build_parser() -> argparse.ArgumentParser:
     service.add_argument("--model-name", default="Item", help="Primary model name")
     service.add_argument("--model-name-plural", default="items", help="Plural model name")
     service.add_argument(
-        "--database", choices=["sqlite", "maria", "postgres", "none"], default="sqlite"
+        "--database", choices=["sqlite", "maria", "postgres", "none"], default="none"
     )
     service.add_argument("--delegates", action="store_true", help="Enable delegates")
     service.add_argument("--upstreams", default="", help="Comma-separated upstream URLs")
@@ -219,7 +308,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "--structured-logging",
         dest="structured_logging",
         action="store_true",
-        default=True,
+        default=False,
         help="Enable structured logging",
     )
     service.add_argument(
@@ -232,6 +321,18 @@ def _build_parser() -> argparse.ArgumentParser:
     service.add_argument("--no-interactive", dest="interactive", action="store_false")
     service.add_argument("--force", action="store_true", help="Overwrite existing generated path")
 
+    cluster = new_sub.add_parser("cluster", help="Generate a cluster scaffold from spec or prompts")
+    cluster.add_argument("--name", help="Cluster name (used in interactive mode)")
+    cluster.add_argument("--spec", type=Path, help="Path to cluster YAML spec")
+    cluster.add_argument("--output", type=Path, default=Path.cwd(), help="Output directory")
+    cluster.add_argument(
+        "--preset",
+        choices=list(PRESETS.keys()),
+        default="none",
+        help="Interactive preset to seed platform services",
+    )
+    cluster.add_argument("--force", action="store_true", help="Overwrite existing generated path")
+
     return parser
 
 
@@ -277,8 +378,8 @@ def main() -> int:
 
     if args.command == "new" and args.new_command == "service":
         try:
-            config = _collect_new_service_config(args)
-            generated = generate_service(**config)
+            service_config = _collect_new_service_config(args)
+            generated = generate_service(**service_config)
         except (FileExistsError, ValueError) as exc:
             print(f"ERROR: {exc}")
             return 1
@@ -288,6 +389,23 @@ def main() -> int:
         print(f"Generated service at: {generated}")
         return 0
 
+    if args.command == "new" and args.new_command == "cluster":
+        try:
+            cluster_config = _collect_new_cluster_config(args)
+            generated = generate_cluster(
+                cluster_config["spec"],
+                cluster_config["output_dir"],
+                force=cluster_config["overwrite_if_exists"],
+            )
+        except (FileExistsError, ValueError) as exc:
+            print(f"ERROR: {exc}")
+            return 1
+        except KeyboardInterrupt:
+            print("\nCancelled.")
+            return 1
+        print(f"Generated cluster at: {generated}")
+        return 0
+
     if args.command == "doctor":
         return _run_doctor(args.service, args.json)
 

csrd_utils-0.3.9/src/csrd_utils/cluster.py

@@ -0,0 +1,457 @@
+"""Cluster scaffolding helpers for csrd-utils."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, TypedDict, cast
+
+import yaml  # type: ignore[import-untyped]
+
+
+class ServiceSpec(TypedDict, total=False):
+    name: str
+    type: str
+    database: str
+    delegates: list[str]
+    broker: str
+    role: str
+    port: int
+    features: list[str]
+    requires: list[str]
+
+
+class ClusterSpec(TypedDict):
+    cluster: dict[str, str]
+    services: list[ServiceSpec]
+
+
+INFRA_NAMES = {"postgres", "mariadb", "redis", "rabbitmq"}
+DEFAULT_PORT_START = 8091
+
+PRESETS: dict[str, list[ServiceSpec]] = {
+    "none": [],
+    "authenticated-cluster": [
+        {"name": "auth-service", "type": "platform", "role": "auth", "port": 8081, "requires": []},
+        {
+            "name": "identity-service",
+            "type": "platform",
+            "role": "identity",
+            "port": 8082,
+            "requires": ["auth-service"],
+        },
+    ],
+    "minimal-cluster": [
+        {"name": "auth-service", "type": "platform", "role": "auth", "port": 8081, "requires": []},
+        {
+            "name": "core-db",
+            "type": "db",
+            "database": "sqlite",
+            "port": 8091,
+            "requires": ["auth-service"],
+        },
+    ],
+    "event-driven-cluster": [
+        {"name": "auth-service", "type": "platform", "role": "auth", "port": 8081, "requires": []},
+        {
+            "name": "events",
+            "type": "db",
+            "database": "postgres",
+            "port": 8091,
+            "requires": ["auth-service"],
+        },
+        {
+            "name": "worker-consume",
+            "type": "worker",
+            "broker": "redis",
+            "port": 8093,
+            "requires": ["events", "redis"],
+        },
+    ],
+}
+
+
+def _split_csv(raw: str) -> list[str]:
+    return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+def load_cluster_spec(spec_path: Path) -> ClusterSpec:
+    payload = yaml.safe_load(spec_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("Cluster spec must be a YAML object")
+    cluster = payload.get("cluster")
+    services = payload.get("services")
+    if not isinstance(cluster, dict) or not isinstance(services, list):
+        raise ValueError("Cluster spec must include 'cluster' object and 'services' list")
+
+    name = str(cluster.get("name", "")).strip()
+    if not name:
+        raise ValueError("cluster.name is required")
+
+    preset = str(cluster.get("preset", "none")).strip() or "none"
+    parsed_services: list[ServiceSpec] = [
+        cast(ServiceSpec, dict(service)) for service in services if isinstance(service, dict)
+    ]
+
+    return {
+        "cluster": {"name": name, "preset": preset},
+        "services": parsed_services,
+    }
+
+
+def normalize_cluster_spec(spec: ClusterSpec) -> ClusterSpec:
+    cluster_name = spec["cluster"]["name"].strip()
+    preset = spec["cluster"].get("preset", "none").strip() or "none"
+    if preset not in PRESETS:
+        raise ValueError(f"Unknown preset: {preset}")
+
+    services: list[ServiceSpec] = [cast(ServiceSpec, dict(service)) for service in PRESETS[preset]]
+    services.extend(cast(ServiceSpec, dict(service)) for service in spec.get("services", []))
+
+    used_names: set[str] = set()
+    used_ports: set[int] = set()
+    next_port = DEFAULT_PORT_START
+    normalized: list[ServiceSpec] = []
+
+    for service in services:
+        name = str(service.get("name", "")).strip()
+        if not name:
+            raise ValueError("Each service requires a name")
+        if name in used_names:
+            raise ValueError(f"Duplicate service name: {name}")
+        used_names.add(name)
+
+        service_type = str(service.get("type", "")).strip()
+        if service_type not in {"db", "delegate", "worker", "platform"}:
+            raise ValueError(f"Unsupported service type for {name}: {service_type}")
+
+        normalized_service: ServiceSpec = {
+            "name": name,
+            "type": service_type,
+            "features": list(service.get("features", [])),
+            "requires": list(service.get("requires", [])),
+        }
+
+        port = service.get("port")
+        if port is None:
+            while next_port in used_ports:
+                next_port += 1
+            port = next_port
+            next_port += 1
+        if int(port) in used_ports:
+            raise ValueError(f"Duplicate port detected: {port}")
+        normalized_service["port"] = int(port)
+        used_ports.add(int(port))
+
+        if service_type == "db":
+            database = str(service.get("database", "")).strip()
+            if database not in {"sqlite", "maria", "postgres"}:
+                raise ValueError(f"DB service '{name}' requires database sqlite/maria/postgres")
+            normalized_service["database"] = database
+
+        if service_type == "delegate":
+            delegates = service.get("delegates", [])
+            if isinstance(delegates, str):
+                delegates = _split_csv(delegates)
+            normalized_service["delegates"] = list(delegates)
+
+        if service_type == "worker":
+            broker = str(service.get("broker", "")).strip() or "redis"
+            if broker not in {"redis", "rabbitmq"}:
+                raise ValueError(f"Worker service '{name}' requires broker redis/rabbitmq")
+            normalized_service["broker"] = broker
+
+        if service_type == "platform":
+            normalized_service["role"] = str(service.get("role", "custom")).strip() or "custom"
+
+        normalized.append(normalized_service)
+
+    _validate_dependencies(normalized)
+    _validate_cycles(normalized)
+
+    return {"cluster": {"name": cluster_name, "preset": preset}, "services": normalized}
+
+
+def _validate_dependencies(services: list[ServiceSpec]) -> None:
+    names = {str(service["name"]) for service in services}
+
+    for service in services:
+        name = str(service["name"])
+        delegates = service.get("delegates", [])
+        for target in delegates:
+            if target not in names:
+                raise ValueError(f"Service '{name}' delegates to unknown service '{target}'")
+
+        requires = service.get("requires", [])
+        for required in requires:
+            if required not in names and required not in INFRA_NAMES:
+                raise ValueError(f"Service '{name}' requires unknown dependency '{required}'")
+
+
+def _validate_cycles(services: list[ServiceSpec]) -> None:
+    names = {str(service["name"]) for service in services}
+    graph: dict[str, list[str]] = {}
+    for service in services:
+        name = str(service["name"])
+        graph[name] = [dep for dep in service.get("requires", []) if dep in names]
+
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def walk(node: str) -> None:
+        if node in visited:
+            return
+        if node in visiting:
+            raise ValueError(f"Circular dependency detected at '{node}'")
+        visiting.add(node)
+        for nxt in graph.get(node, []):
+            walk(nxt)
+        visiting.remove(node)
+        visited.add(node)
+
+    for node in graph:
+        walk(node)
+
+
+def _infer_infra(services: Iterable[ServiceSpec]) -> set[str]:
+    infra: set[str] = set()
+    for service in services:
+        service_type = service["type"]
+        if service_type == "db":
+            db = service.get("database")
+            if db == "postgres":
+                infra.add("postgres")
+            if db == "maria":
+                infra.add("mariadb")
+        if service_type == "worker":
+            broker = service.get("broker", "redis")
+            infra.add("redis" if broker == "redis" else "rabbitmq")
+        if "caching" in service.get("features", []):
+            infra.add("redis")
+    return infra
+
+
+def _service_environment(service: ServiceSpec, services: list[ServiceSpec]) -> dict[str, str]:
+    env: dict[str, str] = {"PORT": str(service["port"])}
+    name = str(service["name"])
+
+    if service["type"] == "db":
+        db = service.get("database")
+        if db == "sqlite":
+            env["DB_PATH"] = "./sandbox.db"
+        elif db == "maria":
+            env["DB_HOST"] = "mariadb"
+            env["DB_PORT"] = "3306"
+            env["DB_USER"] = "sandbox"
+            env["DB_PASSWORD"] = "sandbox"
+            env["DB_NAME"] = "sandbox"
+        elif db == "postgres":
+            env["DB_HOST"] = "postgres"
+            env["DB_PORT"] = "5432"
+            env["DB_USER"] = "sandbox"
+            env["DB_PASSWORD"] = "sandbox"
+            env["DB_NAME"] = "sandbox"
+
+    if service["type"] == "worker":
+        broker = service.get("broker", "redis")
+        if broker == "redis":
+            env["CELERY_BROKER_URL"] = "redis://redis:6379/0"
+            env["CELERY_RESULT_BACKEND"] = "redis://redis:6379/1"
+        else:
+            env["CELERY_BROKER_URL"] = "amqp://guest:guest@rabbitmq:5672//"
+            env["CELERY_RESULT_BACKEND"] = "rpc://"
+
+    for target in service.get("delegates", []):
+        target_service = next((s for s in services if s["name"] == target), None)
+        if target_service is not None:
+            key = f"{target.upper().replace('-', '_')}_URL"
+            env[key] = f"http://{target}:{target_service['port']}"
+
+    auth_service = next((s for s in services if s.get("role") == "auth"), None)
+    if auth_service and name != auth_service["name"]:
+        env["AUTH_SERVICE_URL"] = f"http://{auth_service['name']}:{auth_service['port']}"
+
+    return env
+
+
+def render_compose(spec: ClusterSpec) -> dict[str, Any]:
+    services = spec["services"]
+    infra = _infer_infra(services)
+    compose: dict[str, Any] = {"version": "3.9", "services": {}}
+
+    for service in services:
+        name = str(service["name"])
+        requires = {
+            dep
+            for dep in service.get("requires", [])
+            if dep in INFRA_NAMES or any(s["name"] == dep for s in services)
+        }
+
+        # Auto-wire required infra based on selected DB/broker/features.
+        if service["type"] == "db":
+            database = service.get("database")
+            if database == "postgres":
+                requires.add("postgres")
+            elif database == "maria":
+                requires.add("mariadb")
+
+        if service["type"] == "worker":
+            requires.add("redis" if service.get("broker", "redis") == "redis" else "rabbitmq")
+
+        if "caching" in service.get("features", []):
+            requires.add("redis")
+
+        depends_on: dict[str, dict[str, str]] = {}
+        for dep in sorted(requires):
+            condition = "service_started"
+            if dep in {"postgres", "mariadb", "redis", "rabbitmq"}:
+                condition = "service_healthy"
+            depends_on[dep] = {"condition": condition}
+
+        app_service: dict[str, Any] = {
+            "image": f"ghcr.io/csrd-api/{name}:latest",
+            "ports": [f"{service['port']}:{service['port']}"],
+            "environment": _service_environment(service, services),
+        }
+        if depends_on:
+            app_service["depends_on"] = depends_on
+        compose["services"][name] = app_service
+
+    if "postgres" in infra:
+        compose["services"]["postgres"] = {
+            "image": "postgres:16",
+            "environment": {
+                "POSTGRES_DB": "sandbox",
+                "POSTGRES_USER": "sandbox",
+                "POSTGRES_PASSWORD": "sandbox",
+            },
+            "ports": ["5432:5432"],
+            "healthcheck": {
+                "test": ["CMD-SHELL", "pg_isready -U sandbox"],
+                "interval": "10s",
+                "timeout": "5s",
+                "retries": 5,
+            },
+        }
+
+    if "mariadb" in infra:
+        compose["services"]["mariadb"] = {
+            "image": "mariadb:11",
+            "environment": {
+                "MYSQL_ROOT_PASSWORD": "root",
+                "MYSQL_DATABASE": "sandbox",
+                "MYSQL_USER": "sandbox",
+                "MYSQL_PASSWORD": "sandbox",
+            },
+            "ports": ["3306:3306"],
+            "healthcheck": {
+                "test": ["CMD", "mysqladmin", "ping", "-h", "localhost"],
+                "interval": "10s",
+                "timeout": "5s",
+                "retries": 5,
+            },
+        }
+
+    if "redis" in infra:
+        compose["services"]["redis"] = {
+            "image": "redis:7",
+            "ports": ["6379:6379"],
+            "healthcheck": {
+                "test": ["CMD", "redis-cli", "ping"],
+                "interval": "10s",
+                "timeout": "5s",
+                "retries": 5,
+            },
+        }
+
+    if "rabbitmq" in infra:
+        compose["services"]["rabbitmq"] = {
+            "image": "rabbitmq:3-management",
+            "ports": ["5672:5672", "15672:15672"],
+            "healthcheck": {
+                "test": ["CMD", "rabbitmq-diagnostics", "-q", "ping"],
+                "interval": "10s",
+                "timeout": "5s",
+                "retries": 5,
+            },
+        }
+
+    return compose
+
+
+def _build_env(spec: ClusterSpec) -> str:
+    lines = [
+        "# Cluster-level environment",
+        f"CLUSTER_NAME={spec['cluster']['name']}",
+        "",
+        "# Service URLs",
+    ]
+    for service in spec["services"]:
+        key = f"{service['name'].upper().replace('-', '_')}_URL"
+        lines.append(f"{key}=http://localhost:{service['port']}")
+    return "\n".join(lines).strip() + "\n"
+
+
+def _build_readme(spec: ClusterSpec) -> str:
+    lines = [
+        f"# {spec['cluster']['name']}",
+        "",
+        "Generated cluster scaffold.",
+        "",
+        "## Services",
+    ]
+    for service in spec["services"]:
+        lines.append(f"- `{service['name']}` ({service['type']}) on port `{service['port']}`")
+    lines.extend(
+        [
+            "",
+            "## Run",
+            "",
+            "```bash",
+            "docker compose up -d",
+            "./smoke.sh",
+            "```",
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _build_smoke(spec: ClusterSpec) -> str:
+    lines = [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        "",
+        'echo "Running cluster smoke checks..."',
+    ]
+    for service in spec["services"]:
+        lines.extend(
+            [
+                f'echo "- {service["name"]}"',
+                f'curl -fsS "http://localhost:{service["port"]}/health" >/dev/null || true',
+            ]
+        )
+    lines.append('echo "Smoke checks complete."')
+    return "\n".join(lines) + "\n"
+
+
+def generate_cluster(spec: ClusterSpec, output_dir: Path, force: bool = False) -> Path:
+    normalized = normalize_cluster_spec(spec)
+    cluster_root = output_dir.resolve() / normalized["cluster"]["name"]
+    cluster_root.mkdir(parents=True, exist_ok=True)
+
+    if any(cluster_root.iterdir()) and not force:
+        raise FileExistsError(
+            f"Target directory already exists and is not empty: {cluster_root}. Use --force to overwrite."
+        )
+
+    compose = render_compose(normalized)
+    (cluster_root / "docker-compose.yml").write_text(
+        yaml.safe_dump(compose, sort_keys=False), encoding="utf-8"
+    )
+    (cluster_root / ".env.example").write_text(_build_env(normalized), encoding="utf-8")
+    (cluster_root / "README.md").write_text(_build_readme(normalized), encoding="utf-8")
+    smoke_path = cluster_root / "smoke.sh"
+    smoke_path.write_text(_build_smoke(normalized), encoding="utf-8")
+    smoke_path.chmod(0o755)
+
+    return cluster_root