csrd-utils 0.3.13__tar.gz → 0.3.14__tar.gz

{csrd_utils-0.3.13 → csrd_utils-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.13
+Version: 0.3.14
 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,11 +26,13 @@ pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#sub
 ```bash
 csrd --help
 csrd --version
-csrd new service                                  # compact interactive mode (prompts 1-6, then advanced gate)
+csrd new workspace                                # create workspace, then choose none/service/cluster
+csrd new service                                  # requires workspace; prompts to create one if missing
 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 new service --name inventory --no-interactive --output ./my-workspace
+csrd new service --name pricing --output ./my-workspace --no-interactive
+csrd new cluster --spec ./cluster.yaml --output ./my-workspace
+csrd new cluster                                  # requires workspace; interactive mode can offer to create one
 csrd feature list
 csrd feature plan workers --service .
 csrd feature plan workers --service . --json
@@ -42,7 +44,14 @@ csrd doctor --service .
 
 ### Interactive generation behavior
 
+- `csrd new service` and `csrd new cluster` are workspace-first commands.
+- If a workspace marker is missing in the selected output path, interactive flows ask to create one and continue.
+- Non-interactive generation errors when no workspace marker is present.
+- Workspace cluster source of truth is persisted at `.csrd/cluster.yaml`.
+- If `.csrd/cluster.yaml` already exists, `csrd new service` appends the generated service and refreshes scaffold files (`docker-compose.yml`, `.env.example`, `README.md`, `smoke.sh`). Service source directories and running containers are never touched.
+- If `.csrd/cluster.yaml` is missing and a second service is added to the workspace, `csrd new service` bootstraps `.csrd/cluster.yaml` and writes initial cluster scaffold files.
 - `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
+- `csrd new workspace` creates a workspace directory and prompts whether to generate `none`, `service`, or `cluster` immediately.
 - 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.
@@ -54,20 +63,24 @@ csrd doctor --service .
 ## Typical workflow
 
 ```bash
-# 0) Generate a new service from bundled template
-csrd new service --name inventory --output . --database postgres --workers
+# 0) Create a workspace and generate a service inside it
+csrd new workspace --name local-dev --output . --generate none
+csrd new service --name inventory --output ./local-dev --database postgres --workers
 
 # 1) Verify service compatibility
-csrd doctor --service ./inventory
+csrd doctor --service ./local-dev/inventory
 
 # 2) Inspect available bundled features
 csrd feature list
 
 # 3) Dry-run a feature
-csrd feature plan workers --service ./inventory
+csrd feature plan workers --service ./local-dev/inventory
 
 # 4) Apply feature files/merges
-csrd feature add workers --service ./inventory
+csrd feature add workers --service ./local-dev/inventory
+
+# 5) Add a second service — workspace auto-upgrades to cluster
+csrd new service --name pricing --output ./local-dev --database postgres
 ```
 
 ## Bundled assets
@@ -102,6 +115,8 @@ If an agent can only see the installed CLI (not source files), use this explorat
 ```bash
 csrd --help
 csrd new --help
+csrd new workspace --help
+csrd new service --help
 csrd new cluster --help
 csrd feature --help
 csrd doctor --help
@@ -112,10 +127,9 @@ Then run a clean smoke flow:
 
 ```bash
 mkdir -p /tmp/csrd-smoke
-cd /tmp/csrd-smoke
-csrd new service --name demo-svc --output . --no-interactive
-cd demo-svc
-csrd doctor
-csrd feature plan workers
-csrd feature add workers
+csrd new workspace --name ws --output /tmp/csrd-smoke --generate none
+csrd new service --name demo-svc --output /tmp/csrd-smoke/ws --no-interactive
+csrd doctor --service /tmp/csrd-smoke/ws/demo-svc
+csrd feature plan workers --service /tmp/csrd-smoke/ws/demo-svc
+csrd feature add workers --service /tmp/csrd-smoke/ws/demo-svc
 ```

{csrd_utils-0.3.13 → csrd_utils-0.3.14}/README.md

@@ -13,11 +13,13 @@ pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#sub
 ```bash
 csrd --help
 csrd --version
-csrd new service                                  # compact interactive mode (prompts 1-6, then advanced gate)
+csrd new workspace                                # create workspace, then choose none/service/cluster
+csrd new service                                  # requires workspace; prompts to create one if missing
 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 new service --name inventory --no-interactive --output ./my-workspace
+csrd new service --name pricing --output ./my-workspace --no-interactive
+csrd new cluster --spec ./cluster.yaml --output ./my-workspace
+csrd new cluster                                  # requires workspace; interactive mode can offer to create one
 csrd feature list
 csrd feature plan workers --service .
 csrd feature plan workers --service . --json
@@ -29,7 +31,14 @@ csrd doctor --service .
 
 ### Interactive generation behavior
 
+- `csrd new service` and `csrd new cluster` are workspace-first commands.
+- If a workspace marker is missing in the selected output path, interactive flows ask to create one and continue.
+- Non-interactive generation errors when no workspace marker is present.
+- Workspace cluster source of truth is persisted at `.csrd/cluster.yaml`.
+- If `.csrd/cluster.yaml` already exists, `csrd new service` appends the generated service and refreshes scaffold files (`docker-compose.yml`, `.env.example`, `README.md`, `smoke.sh`). Service source directories and running containers are never touched.
+- If `.csrd/cluster.yaml` is missing and a second service is added to the workspace, `csrd new service` bootstraps `.csrd/cluster.yaml` and writes initial cluster scaffold files.
 - `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
+- `csrd new workspace` creates a workspace directory and prompts whether to generate `none`, `service`, or `cluster` immediately.
 - 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.
@@ -41,20 +50,24 @@ csrd doctor --service .
 ## Typical workflow
 
 ```bash
-# 0) Generate a new service from bundled template
-csrd new service --name inventory --output . --database postgres --workers
+# 0) Create a workspace and generate a service inside it
+csrd new workspace --name local-dev --output . --generate none
+csrd new service --name inventory --output ./local-dev --database postgres --workers
 
 # 1) Verify service compatibility
-csrd doctor --service ./inventory
+csrd doctor --service ./local-dev/inventory
 
 # 2) Inspect available bundled features
 csrd feature list
 
 # 3) Dry-run a feature
-csrd feature plan workers --service ./inventory
+csrd feature plan workers --service ./local-dev/inventory
 
 # 4) Apply feature files/merges
-csrd feature add workers --service ./inventory
+csrd feature add workers --service ./local-dev/inventory
+
+# 5) Add a second service — workspace auto-upgrades to cluster
+csrd new service --name pricing --output ./local-dev --database postgres
 ```
 
 ## Bundled assets
@@ -89,6 +102,8 @@ If an agent can only see the installed CLI (not source files), use this explorat
 ```bash
 csrd --help
 csrd new --help
+csrd new workspace --help
+csrd new service --help
 csrd new cluster --help
 csrd feature --help
 csrd doctor --help
@@ -99,10 +114,9 @@ Then run a clean smoke flow:
 
 ```bash
 mkdir -p /tmp/csrd-smoke
-cd /tmp/csrd-smoke
-csrd new service --name demo-svc --output . --no-interactive
-cd demo-svc
-csrd doctor
-csrd feature plan workers
-csrd feature add workers
+csrd new workspace --name ws --output /tmp/csrd-smoke --generate none
+csrd new service --name demo-svc --output /tmp/csrd-smoke/ws --no-interactive
+csrd doctor --service /tmp/csrd-smoke/ws/demo-svc
+csrd feature plan workers --service /tmp/csrd-smoke/ws/demo-svc
+csrd feature add workers --service /tmp/csrd-smoke/ws/demo-svc
 ```

{csrd_utils-0.3.13 → csrd_utils-0.3.14}/pyproject.toml

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

{csrd_utils-0.3.13 → csrd_utils-0.3.14}/src/csrd_utils/__main__.py

@@ -8,9 +8,19 @@ from contextlib import suppress
 from importlib.metadata import version
 from pathlib import Path
 from typing import TypedDict
+from urllib.parse import urlparse
+
+import yaml  # type: ignore[import-untyped]
 
 from .augmentor import ServiceAugmentor
-from .cluster import PRESETS, ClusterSpec, ServiceSpec, generate_cluster, load_cluster_spec
+from .cluster import (
+    PRESETS,
+    ClusterSpec,
+    ServiceSpec,
+    generate_cluster,
+    load_cluster_spec,
+    normalize_cluster_spec,
+)
 from .doctor import run_doctor
 from .generator import generate_service
 from .resources import features_path
@@ -41,6 +51,17 @@ class GenerateClusterArgs(TypedDict):
     overwrite_if_exists: bool
 
 
+class GenerateWorkspaceArgs(TypedDict):
+    name: str
+    output_dir: Path
+    overwrite_if_exists: bool
+    generate: str
+
+
+WORKSPACE_MARKER = ".csrd-workspace"
+WORKSPACE_CLUSTER_SPEC = Path(".csrd") / "cluster.yaml"
+
+
 def _prompt_text(label: str, default: str) -> str:
     value = input(f"{label} [{default}]: ").strip()
     return value or default
@@ -263,6 +284,298 @@ def _collect_new_cluster_config(args: argparse.Namespace) -> GenerateClusterArgs
     )
 
 
+def _collect_new_workspace_config(args: argparse.Namespace) -> GenerateWorkspaceArgs:
+    name = args.name or _prompt_text("Workspace name", "my-workspace")
+    output_dir = (
+        args.output
+        if args.name is not None
+        else Path(_prompt_text("Output directory", str(args.output)))
+    )
+    generate = args.generate or _prompt_choice(
+        "Generate in workspace now", ["none", "service", "cluster"], "none"
+    )
+    return GenerateWorkspaceArgs(
+        {
+            "name": name,
+            "output_dir": output_dir,
+            "overwrite_if_exists": args.force,
+            "generate": generate,
+        }
+    )
+
+
+def _create_workspace(config: GenerateWorkspaceArgs) -> Path:
+    workspace_root = config["output_dir"].resolve() / config["name"]
+    if workspace_root.exists() and not workspace_root.is_dir():
+        raise FileExistsError(f"Target path exists and is not a directory: {workspace_root}")
+
+    workspace_root.mkdir(parents=True, exist_ok=True)
+    if any(workspace_root.iterdir()) and not config["overwrite_if_exists"]:
+        raise FileExistsError(
+            f"Target directory already exists and is not empty: {workspace_root}. Use --force to overwrite."
+        )
+
+    _write_workspace_marker(workspace_root)
+    return workspace_root
+
+
+def _default_service_namespace(output_dir: Path) -> argparse.Namespace:
+    return argparse.Namespace(
+        interactive=True,
+        name=None,
+        output=output_dir,
+        description="A microservice using the csrd library stack",
+        port=8080,
+        model_name="Item",
+        model_name_plural="items",
+        database="none",
+        delegates=False,
+        upstreams="",
+        workers=False,
+        broker="redis",
+        caching=False,
+        cache_backend="redis",
+        structured_logging=False,
+        force=False,
+    )
+
+
+def _default_cluster_namespace(output_dir: Path) -> argparse.Namespace:
+    return argparse.Namespace(
+        spec=None,
+        name=None,
+        output=output_dir,
+        preset="none",
+        force=False,
+    )
+
+
+def _write_workspace_marker(path: Path) -> None:
+    (path / WORKSPACE_MARKER).write_text("workspace: csrd\n", encoding="utf-8")
+
+
+def _is_workspace(path: Path) -> bool:
+    return (path / WORKSPACE_MARKER).is_file()
+
+
+def _service_is_interactive(args: argparse.Namespace) -> bool:
+    explicit_interactive = getattr(args, "interactive", None)
+    return bool(explicit_interactive) if explicit_interactive is not None else args.name is None
+
+
+def _ensure_workspace_for_output(output_dir: Path, allow_prompt: bool) -> Path:
+    workspace_root = output_dir.resolve()
+    if _is_workspace(workspace_root):
+        return workspace_root
+
+    if workspace_root.exists() and not workspace_root.is_dir():
+        raise ValueError(f"Output path is not a directory: {workspace_root}")
+
+    if allow_prompt:
+        create_workspace = _prompt_bool(
+            f"No workspace found at {workspace_root}. Create workspace marker here", True
+        )
+        if create_workspace:
+            workspace_root.mkdir(parents=True, exist_ok=True)
+            _write_workspace_marker(workspace_root)
+            print(f"Generated workspace at: {workspace_root}")
+            return workspace_root
+
+    raise ValueError(
+        "This command requires a csrd workspace. Run 'csrd new workspace' first or use a workspace output path."
+    )
+
+
+def _workspace_cluster_spec_path(workspace_root: Path) -> Path:
+    return workspace_root / WORKSPACE_CLUSTER_SPEC
+
+
+def _load_workspace_cluster_spec(workspace_root: Path) -> ClusterSpec:
+    spec_path = _workspace_cluster_spec_path(workspace_root)
+    if spec_path.is_file():
+        return load_cluster_spec(spec_path)
+    return {
+        "cluster": {"name": workspace_root.name, "preset": "none"},
+        "services": [],
+    }
+
+
+def _save_workspace_cluster_spec(workspace_root: Path, spec: ClusterSpec) -> None:
+    spec_path = _workspace_cluster_spec_path(workspace_root)
+    spec_path.parent.mkdir(parents=True, exist_ok=True)
+    normalized = normalize_cluster_spec(spec)
+    spec_path.write_text(yaml.safe_dump(normalized, sort_keys=False), encoding="utf-8")
+
+
+def _delegate_targets_from_upstreams(raw_upstreams: str) -> list[str]:
+    targets: list[str] = []
+    for raw in [entry.strip() for entry in raw_upstreams.split(",") if entry.strip()]:
+        parsed = urlparse(raw)
+        if not parsed.hostname:
+            raise ValueError(
+                f"Unable to infer delegate target from upstream URL: {raw}. Use full URLs with hostnames."
+            )
+        targets.append(parsed.hostname)
+    return targets
+
+
+def _service_config_to_cluster_service(config: GenerateServiceArgs) -> ServiceSpec:
+    has_database = config["has_database"]
+    has_workers = config["has_workers"]
+    has_delegates = config["has_delegates"]
+    selected_roles = sum(1 for enabled in (has_database, has_workers, has_delegates) if enabled)
+    if selected_roles > 1:
+        raise ValueError(
+            "Workspace cluster mapping supports one core role per generated service (database or workers or delegates)."
+        )
+
+    service: ServiceSpec = {
+        "name": config["name"],
+        "port": config["port"],
+        "features": [],
+        "requires": [],
+    }
+
+    if has_database:
+        service["type"] = "db"
+        service["database"] = config["database"]
+    elif has_workers:
+        service["type"] = "worker"
+        service["broker"] = config["broker"]
+        service["requires"] = ["redis" if config["broker"] == "redis" else "rabbitmq"]
+    elif has_delegates:
+        targets = _delegate_targets_from_upstreams(config["upstreams"])
+        service["type"] = "delegate"
+        service["delegates"] = targets
+        service["requires"] = list(targets)
+    else:
+        service["type"] = "platform"
+        service["role"] = "custom"
+
+    if config["has_caching"]:
+        service["features"].append("caching")
+    if config["has_structured_logging"]:
+        service["features"].append("logging")
+
+    return service
+
+
+def _append_service_to_workspace_cluster(
+    workspace_root: Path, config: GenerateServiceArgs
+) -> ClusterSpec:
+    spec = _load_workspace_cluster_spec(workspace_root)
+    service_names = {str(service.get("name", "")).strip() for service in spec.get("services", [])}
+    if config["name"] in service_names:
+        raise ValueError(f"Service '{config['name']}' already exists in workspace cluster spec")
+
+    spec["services"].append(_service_config_to_cluster_service(config))
+    normalized = normalize_cluster_spec(spec)
+    _save_workspace_cluster_spec(workspace_root, normalized)
+    return normalized
+
+
+def _workspace_service_roots(workspace_root: Path) -> list[Path]:
+    roots: list[Path] = []
+    for child in workspace_root.iterdir():
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        if (
+            (child / "src" / "app").is_dir()
+            and (child / "tests").is_dir()
+            and (child / "requirements.txt").is_file()
+            and (child / "docker-compose.yml").is_file()
+        ):
+            roots.append(child)
+    return sorted(roots)
+
+
+def _infer_port_from_service_root(service_root: Path) -> int:
+    try:
+        payload = yaml.safe_load((service_root / "docker-compose.yml").read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return 8080
+
+    if not isinstance(payload, dict):
+        return 8080
+    services = payload.get("services")
+    if not isinstance(services, dict) or not services:
+        return 8080
+
+    first_service = next(iter(services.values()))
+    if not isinstance(first_service, dict):
+        return 8080
+    ports = first_service.get("ports")
+    if not isinstance(ports, list) or not ports:
+        return 8080
+
+    first_port = ports[0]
+    if isinstance(first_port, int):
+        return first_port
+    if isinstance(first_port, str):
+        host_port = first_port.split(":", maxsplit=1)[0].strip()
+        if host_port.isdigit():
+            return int(host_port)
+    return 8080
+
+
+def _infer_existing_workspace_service(service_root: Path) -> ServiceSpec:
+    return {
+        "name": service_root.name,
+        "type": "platform",
+        "role": "custom",
+        "port": _infer_port_from_service_root(service_root),
+        "features": [],
+        "requires": [],
+    }
+
+
+def _ensure_unique_ports(services: list[ServiceSpec], preserve_name: str) -> None:
+    preserve = next((service for service in services if service["name"] == preserve_name), None)
+    used: set[int] = set()
+    if preserve is not None:
+        used.add(int(preserve["port"]))
+
+    for service in services:
+        if service["name"] == preserve_name:
+            continue
+        port = int(service["port"])
+        while port in used:
+            port += 1
+        service["port"] = port
+        used.add(port)
+
+
+def _maybe_update_workspace_cluster(
+    workspace_root: Path,
+    service_config: GenerateServiceArgs,
+    generated_service: Path,
+) -> Path | None:
+    spec_path = _workspace_cluster_spec_path(workspace_root)
+    if spec_path.is_file():
+        updated_spec = _append_service_to_workspace_cluster(workspace_root, service_config)
+        return generate_cluster(updated_spec, workspace_root, force=True)
+
+    service_roots = _workspace_service_roots(workspace_root)
+    if len(service_roots) < 2:
+        return None
+
+    generated_name = generated_service.name
+    services: list[ServiceSpec] = [_service_config_to_cluster_service(service_config)]
+    for service_root in service_roots:
+        if service_root.name != generated_name:
+            services.append(_infer_existing_workspace_service(service_root))
+
+    _ensure_unique_ports(services, preserve_name=generated_name)
+
+    bootstrap_spec: ClusterSpec = {
+        "cluster": {"name": workspace_root.name, "preset": "none"},
+        "services": services,
+    }
+    normalized = normalize_cluster_spec(bootstrap_spec)
+    _save_workspace_cluster_spec(workspace_root, normalized)
+    return generate_cluster(normalized, workspace_root, force=True)
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="csrd", description="csrd utilities")
     parser.add_argument(
@@ -342,6 +655,18 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     cluster.add_argument("--force", action="store_true", help="Overwrite existing generated path")
 
+    workspace = new_sub.add_parser(
+        "workspace", help="Create an empty workspace and optionally generate service/cluster"
+    )
+    workspace.add_argument("--name", help="Workspace directory name")
+    workspace.add_argument("--output", type=Path, default=Path.cwd(), help="Output directory")
+    workspace.add_argument(
+        "--generate",
+        choices=["none", "service", "cluster"],
+        help="Generate an asset inside the workspace after creation",
+    )
+    workspace.add_argument("--force", action="store_true", help="Overwrite existing workspace path")
+
     return parser
 
 
@@ -388,7 +713,15 @@ def main() -> int:
     if args.command == "new" and args.new_command == "service":
         try:
             service_config = _collect_new_service_config(args)
+            service_config["output_dir"] = _ensure_workspace_for_output(
+                service_config["output_dir"], allow_prompt=_service_is_interactive(args)
+            )
             generated = generate_service(**service_config)
+            generated_cluster = _maybe_update_workspace_cluster(
+                service_config["output_dir"], service_config, generated
+            )
+            if generated_cluster is not None:
+                print(f"Refreshed cluster scaffold at: {generated_cluster}")
         except (FileExistsError, ValueError) as exc:
             print(f"ERROR: {exc}")
             return 1
@@ -401,11 +734,15 @@ def main() -> int:
     if args.command == "new" and args.new_command == "cluster":
         try:
             cluster_config = _collect_new_cluster_config(args)
+            cluster_config["output_dir"] = _ensure_workspace_for_output(
+                cluster_config["output_dir"], allow_prompt=args.spec is None
+            )
             generated = generate_cluster(
                 cluster_config["spec"],
                 cluster_config["output_dir"],
                 force=cluster_config["overwrite_if_exists"],
             )
+            _save_workspace_cluster_spec(cluster_config["output_dir"], cluster_config["spec"])
         except (FileExistsError, FileNotFoundError, ValueError) as exc:
             print(f"ERROR: {exc}")
             return 1
@@ -415,6 +752,39 @@ def main() -> int:
         print(f"Generated cluster at: {generated}")
         return 0
 
+    if args.command == "new" and args.new_command == "workspace":
+        try:
+            workspace_config = _collect_new_workspace_config(args)
+            workspace_root = _create_workspace(workspace_config)
+            print(f"Generated workspace at: {workspace_root}")
+
+            generate_mode = workspace_config["generate"]
+            if generate_mode == "service":
+                service_config = _collect_new_service_config(
+                    _default_service_namespace(workspace_root)
+                )
+                service_config["output_dir"] = workspace_root
+                generated_service = generate_service(**service_config)
+                print(f"Generated service at: {generated_service}")
+            elif generate_mode == "cluster":
+                cluster_config = _collect_new_cluster_config(
+                    _default_cluster_namespace(workspace_root)
+                )
+                cluster_config["output_dir"] = workspace_root
+                generated_cluster = generate_cluster(
+                    cluster_config["spec"],
+                    cluster_config["output_dir"],
+                    force=cluster_config["overwrite_if_exists"],
+                )
+                print(f"Generated cluster at: {generated_cluster}")
+        except (FileExistsError, FileNotFoundError, ValueError) as exc:
+            print(f"ERROR: {exc}")
+            return 1
+        except KeyboardInterrupt:
+            _print_cancelled()
+            return 1
+        return 0
+
     if args.command == "doctor":
         return _run_doctor(args.service, args.json)