csrd-utils 0.3.86__tar.gz → 0.3.89__tar.gz

{csrd_utils-0.3.86 → csrd_utils-0.3.89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.86
+Version: 0.3.89
 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

{csrd_utils-0.3.86 → csrd_utils-0.3.89}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.3.86"
+version = "0.3.89"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"
@@ -26,11 +26,12 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/csrd_utils"]
+packages = ["src/csrd_utils", "src/tui_wizard"]
 
 [tool.hatch.build.targets.sdist]
 include = [
     "src/csrd_utils/**",
+    "src/tui_wizard/**",
     "README.md",
     "pyproject.toml",
 ]

{csrd_utils-0.3.86 → csrd_utils-0.3.89}/src/csrd_utils/v2/compose/__init__.py

@@ -8,7 +8,15 @@ from ..models import (
     ComposeSpec,
     InfraNode,
     PresetDefinition,
+    ServiceAugment,
     ServiceNode,
+    WorkspaceAugment,
+)
+from .augments import (
+    AUGMENT_REGISTRY,
+    AugmentDescriptor,
+    augment_for,
+    augments_for_scope,
 )
 from .infra import (
     INFRA_REGISTRY,
@@ -29,10 +37,14 @@ from .loader import (
 from .operations import (
     add_infra,
     add_service,
+    add_service_augment,
+    add_workspace_augment,
     apply,
     available_infra,
+    available_service_augments,
     configured_infra,
     remove_infra,
+    remove_service_augment,
     validate,
 )
 from .presets import (
@@ -41,7 +53,7 @@ from .presets import (
     members_for_category,
 )
 from .renderer import render_workspace
-from .scaffolder import scaffold_service, scaffold_services
+from .scaffolder import scaffold_augment, scaffold_service, scaffold_services
 from .yaml_editor import (
     deep_merge,
     dumps_yaml,
@@ -52,6 +64,7 @@ from .yaml_editor import (
 )
 
 __all__ = [
+    "AUGMENT_REGISTRY",
     "INFRA_ALL_TYPES",
     "INFRA_CATEGORIES",
     "INFRA_DATABASES",
@@ -59,15 +72,23 @@ __all__ = [
     "INFRA_RENDERERS",
     "PRESET_REGISTRY",
     "SPEC_FILENAME",
+    "AugmentDescriptor",
     "ComposeSpec",
     "InfraDescriptor",
     "InfraNode",
     "PresetDefinition",
+    "ServiceAugment",
     "ServiceNode",
+    "WorkspaceAugment",
     "add_infra",
     "add_service",
+    "add_service_augment",
+    "add_workspace_augment",
     "apply",
+    "augment_for",
+    "augments_for_scope",
     "available_infra",
+    "available_service_augments",
     "configured_infra",
     "deep_merge",
     "default_spec",
@@ -81,10 +102,12 @@ __all__ = [
     "load_yaml",
     "members_for_category",
     "remove_infra",
+    "remove_service_augment",
     "render_infra",
     "render_workspace",
     "save_spec",
     "save_yaml",
+    "scaffold_augment",
     "scaffold_service",
     "scaffold_services",
     "set_key",

csrd_utils-0.3.89/src/csrd_utils/v2/compose/augments.py

@@ -0,0 +1,166 @@
+"""Augment descriptors for application-level service capabilities.
+
+Each augment is described by an ``AugmentDescriptor`` dataclass that
+encapsulates everything the renderer and scaffolder need: prerequisite
+checks, compose wiring, package dependencies, settings fields, and
+template references.  Adding a new augment requires only adding a new
+descriptor to ``AUGMENT_REGISTRY``.
+
+Mirrors the ``InfraDescriptor`` pattern in ``infra.py``.
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class AugmentDescriptor:
+    """Complete description of an augment capability.
+
+    Parameters
+    ----------
+    name
+        Unique augment identifier used in specs and registry lookups.
+    scope
+        ``"workspace"`` for cluster-wide facts, ``"service"`` for
+        per-service capabilities.
+    description
+        Human-readable description shown in menus and docs.
+    requires_infra
+        Infra feature categories that must be present in the spec
+        (e.g. ``["database"]``).
+    requires_workspace_augment
+        A workspace-scope augment that must exist for this augment to
+        be valid (e.g. ``"jwt-auth-provider"``).
+    requires_service_in_spec
+        A service role that must exist in the spec.
+    compose_env
+        Static compose environment variables contributed by this augment.
+    compose_depends_on
+        Static compose ``depends_on`` entries.
+    packages
+        Python package names added to the service's ``requirements.txt``.
+    settings_fields
+        Static settings fields (name → default value). Dynamic fields
+        are resolved in the renderer.
+    template_dir
+        Relative name under ``v2/templates/augments/`` for scaffolded
+        files.  ``None`` for workspace-scope augments that don't scaffold.
+    conflicts_with
+        Augment names that cannot coexist with this one.
+    needs_target_selection
+        Whether the wizard should prompt the user to pick target
+        services from the spec (e.g. delegate targets).
+    """
+
+    name: str
+    scope: Literal["workspace", "service"]
+    description: str
+
+    # Prerequisites
+    requires_infra: list[str] = field(default_factory=list)
+    requires_workspace_augment: str | None = None
+    requires_service_in_spec: str | None = None
+
+    # What it contributes to compose (static values only)
+    compose_env: dict[str, str] = field(default_factory=dict)
+    compose_depends_on: list[str] = field(default_factory=list)
+
+    # What it contributes to scaffolded code
+    packages: list[str] = field(default_factory=list)
+    settings_fields: dict[str, str] = field(default_factory=dict)
+    template_dir: str | None = None
+
+    # Conflict prevention
+    conflicts_with: list[str] = field(default_factory=list)
+
+    # Does this augment resolve values dynamically from the spec?
+    needs_target_selection: bool = False
+
+    # For workspace-scope augments: scaffold template files into the
+    # service with this role.  ``None`` means no scaffolding.
+    applies_to_role: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
+    # ── Workspace-scope ────────────────────────────────────────────
+    "jwt-auth-provider": AugmentDescriptor(
+        name="jwt-auth-provider",
+        scope="workspace",
+        description="Cluster provides JWT authentication via an auth service",
+        requires_infra=["database"],
+        packages=[
+            "csrd-auth",
+            "csrd-models",
+            "csrd-repository",
+            "csrd-migration",
+            "PyJWT[crypto]",
+        ],
+        template_dir="jwt-auth-provider",
+        applies_to_role="auth",
+    ),
+    # ── Service-scope ──────────────────────────────────────────────
+    "db-config": AugmentDescriptor(
+        name="db-config",
+        scope="service",
+        description="Database repository with migrations and compose wiring",
+        requires_infra=["database"],
+        packages=["csrd-repository", "csrd-migration"],
+        # settings_fields resolved dynamically per database type in renderer
+        template_dir="db-config",
+    ),
+    "delegate-config": AugmentDescriptor(
+        name="delegate-config",
+        scope="service",
+        description="Inter-service delegation with delegate classes",
+        packages=["csrd-delegate", "csrd-models"],
+        template_dir="delegate-config",
+        needs_target_selection=True,
+        # compose_env and settings_fields are dynamic per target
+    ),
+    "jwt-auth-consumer": AugmentDescriptor(
+        name="jwt-auth-consumer",
+        scope="service",
+        description="JWT token validation using cluster auth service",
+        requires_workspace_augment="jwt-auth-provider",
+        packages=["csrd-auth", "csrd-models"],
+        template_dir="jwt-auth-consumer",
+        # compose_env, compose_depends_on, settings_fields resolved from spec
+    ),
+    "context-logging": AugmentDescriptor(
+        name="context-logging",
+        scope="service",
+        description="Request context middleware and structured logging",
+        packages=["csrd-logging", "csrd-context"],
+        template_dir="context-logging",
+    ),
+    "service-layer": AugmentDescriptor(
+        name="service-layer",
+        scope="service",
+        description="BaseService + ServiceError hierarchy + exception handler",
+        packages=["csrd-service", "csrd-models"],
+        template_dir="service-layer",
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def augment_for(name: str) -> AugmentDescriptor:
+    """Look up an augment descriptor by name.
+
+    Raises ``KeyError`` if the name is not registered.
+    """
+    return AUGMENT_REGISTRY[name]
+
+
+def augments_for_scope(scope: Literal["workspace", "service"]) -> list[AugmentDescriptor]:
+    """Return all augment descriptors matching the given scope."""
+    return [d for d in AUGMENT_REGISTRY.values() if d.scope == scope]

{csrd_utils-0.3.86 → csrd_utils-0.3.89}/src/csrd_utils/v2/compose/infra.py

@@ -7,8 +7,6 @@ volumes, service environment wiring, depends_on entries, and
 a new descriptor to ``INFRA_REGISTRY``.
 """
 
-from __future__ import annotations
-
 from dataclasses import dataclass, field
 from typing import Any
 

csrd_utils-0.3.89/src/csrd_utils/v2/compose/operations.py

@@ -0,0 +1,358 @@
+"""Workspace mutation operations: add/remove services and infra.
+
+These functions load, mutate, and persist the compose spec.  They are
+the canonical way to change a workspace's ``csrd-compose.yaml`` from
+library code or CLI handlers.
+"""
+
+from pathlib import Path
+
+from ..models import (
+    INFRA_ALL_TYPES,
+    INFRA_DATABASES,
+    ComposeSpec,
+    InfraNode,
+    ServiceAugment,
+    ServiceNode,
+    WorkspaceAugment,
+)
+from .augments import AUGMENT_REGISTRY, augment_for
+from .infra import INFRA_REGISTRY
+from .loader import load_spec, save_spec, spec_file_path
+from .renderer import render_workspace
+
+
+def apply(output_dir: Path, *, git_init: bool = False) -> Path:
+    """Apply baseline empty-workspace rendering into *output_dir*."""
+
+    return render_workspace(output_dir, git_init=git_init)
+
+
+def validate(output_dir: Path) -> ComposeSpec:
+    """Validate and return the canonical compose spec for a workspace."""
+
+    return load_spec(spec_file_path(output_dir))
+
+
+def add_service(output_dir: Path, service: ServiceNode) -> ComposeSpec:
+    """Append a service to the workspace spec and persist to disk.
+
+    Raises ``ValueError`` if *service.name* already exists.
+    Returns the updated spec.
+    """
+
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    existing_names = {s.name for s in spec.services}
+    if service.name in existing_names:
+        raise ValueError(f"Service '{service.name}' already exists in workspace spec")
+
+    spec.services.append(service)
+    save_spec(spec, spec_path)
+    return spec
+
+
+def add_infra(output_dir: Path, infra: InfraNode) -> ComposeSpec:
+    """Add or replace an infrastructure entry in the workspace spec.
+
+    Database types are mutually exclusive — adding one replaces any existing
+    database entry.  Other infra types (redis, rabbitmq) are singletons that
+    cannot be duplicated.
+
+    Returns the updated spec.
+    """
+
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    existing_types = {i.type for i in spec.infra}
+
+    if infra.type in INFRA_DATABASES:
+        # Remove any existing database entry (mutually exclusive)
+        spec.infra = [i for i in spec.infra if i.type not in INFRA_DATABASES]
+    elif infra.type in existing_types:
+        raise ValueError(f"Infra '{infra.type}' already exists in workspace spec")
+
+    spec.infra.append(infra)
+    save_spec(spec, spec_path)
+    return spec
+
+
+def remove_infra(output_dir: Path, infra_type: str) -> ComposeSpec:
+    """Remove an infrastructure entry from the workspace spec.
+
+    Raises ``ValueError`` if *infra_type* is not currently configured.
+    Returns the updated spec.
+    """
+
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    existing_types = {i.type for i in spec.infra}
+    if infra_type not in existing_types:
+        raise ValueError(f"Infra '{infra_type}' is not configured in workspace spec")
+
+    spec.infra = [i for i in spec.infra if i.type != infra_type]
+    save_spec(spec, spec_path)
+    return spec
+
+
+def available_infra(workspace_dir: Path) -> list[str]:
+    """Return infra types not yet present in the workspace spec.
+
+    Database types are mutually exclusive — if any database is already
+    configured, all database options are excluded.
+    """
+
+    spec_path = spec_file_path(workspace_dir)
+    if not spec_path.is_file():
+        return sorted(INFRA_ALL_TYPES)
+
+    spec = load_spec(spec_path)
+    existing = {i.type for i in spec.infra}
+
+    available: list[str] = []
+    has_db = bool(existing & INFRA_DATABASES)
+    for infra_type in sorted(INFRA_ALL_TYPES):
+        if infra_type in existing:
+            continue
+        if has_db and infra_type in INFRA_DATABASES:
+            continue
+        available.append(infra_type)
+    return available
+
+
+def configured_infra(workspace_dir: Path) -> list[str]:
+    """Return infra types currently configured in the workspace spec."""
+
+    spec_path = spec_file_path(workspace_dir)
+    if not spec_path.is_file():
+        return []
+
+    spec = load_spec(spec_path)
+    return sorted(i.type for i in spec.infra)
+
+
+# ---------------------------------------------------------------------------
+# Augment operations
+# ---------------------------------------------------------------------------
+
+
+def _infra_features_in_spec(spec: ComposeSpec) -> set[str]:
+    """Return the set of infra feature categories present in the spec."""
+    features: set[str] = set()
+    for infra_node in spec.infra:
+        desc = INFRA_REGISTRY.get(infra_node.type)
+        if desc is not None:
+            features.add(desc.feature)
+    return features
+
+
+def _validate_augment_prerequisites(
+    augment_name: str,
+    spec: ComposeSpec,
+    *,
+    service_name: str | None = None,
+) -> None:
+    """Validate that all prerequisites for an augment are met.
+
+    Raises ``ValueError`` with a descriptive message on failure.
+    """
+    desc = augment_for(augment_name)
+
+    # Check required infra features
+    if desc.requires_infra:
+        spec_features = _infra_features_in_spec(spec)
+        missing = set(desc.requires_infra) - spec_features
+        if missing:
+            raise ValueError(
+                f"Augment '{augment_name}' requires infra features "
+                f"{sorted(missing)}, but they are not configured. "
+                f"Add the required infra first."
+            )
+
+    # Check required workspace augment
+    if desc.requires_workspace_augment:
+        ws_augment_names = {a.name for a in spec.workspace.augments}
+        if desc.requires_workspace_augment not in ws_augment_names:
+            raise ValueError(
+                f"Augment '{augment_name}' requires workspace augment "
+                f"'{desc.requires_workspace_augment}', but it is not present. "
+                f"Add the workspace augment first."
+            )
+
+    # Check required service role in spec
+    if desc.requires_service_in_spec:
+        roles = {s.role for s in spec.services}
+        if desc.requires_service_in_spec not in roles:
+            raise ValueError(
+                f"Augment '{augment_name}' requires a service with role "
+                f"'{desc.requires_service_in_spec}' in the spec."
+            )
+
+    # Check conflicts (only relevant for service-scope augments)
+    if service_name is not None and desc.conflicts_with:
+        svc = next((s for s in spec.services if s.name == service_name), None)
+        if svc is not None:
+            existing = {a.name for a in svc.augments}
+            conflicts = set(desc.conflicts_with) & existing
+            if conflicts:
+                raise ValueError(
+                    f"Augment '{augment_name}' conflicts with "
+                    f"{sorted(conflicts)} on service '{service_name}'."
+                )
+
+
+def add_workspace_augment(
+    output_dir: Path,
+    augment_name: str,
+    options: dict[str, str | list[str]] | None = None,
+) -> ComposeSpec:
+    """Add a workspace-scoped augment to the spec.
+
+    Validates that the augment exists in the registry and has scope
+    ``"workspace"``.  Raises ``ValueError`` on validation failure.
+    Returns the updated spec.
+    """
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    # Validate augment exists and has correct scope
+    try:
+        desc = augment_for(augment_name)
+    except KeyError:
+        raise ValueError(f"Unknown augment '{augment_name}'") from None
+
+    if desc.scope != "workspace":
+        raise ValueError(
+            f"Augment '{augment_name}' has scope '{desc.scope}', "
+            f"not 'workspace'. Use add_service_augment() instead."
+        )
+
+    # Check for duplicates
+    existing = {a.name for a in spec.workspace.augments}
+    if augment_name in existing:
+        raise ValueError(f"Workspace augment '{augment_name}' is already present.")
+
+    _validate_augment_prerequisites(augment_name, spec)
+
+    spec.workspace.augments.append(WorkspaceAugment(name=augment_name, options=options or {}))
+    save_spec(spec, spec_path)
+    return spec
+
+
+def add_service_augment(
+    output_dir: Path,
+    service_name: str,
+    augment_name: str,
+    options: dict[str, str | list[str]] | None = None,
+) -> ComposeSpec:
+    """Add a service-scoped augment to a specific service in the spec.
+
+    Validates prerequisites, scope, duplicates, and conflicts.
+    Raises ``ValueError`` on validation failure.
+    Returns the updated spec.
+    """
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    # Validate augment exists and has correct scope
+    try:
+        desc = augment_for(augment_name)
+    except KeyError:
+        raise ValueError(f"Unknown augment '{augment_name}'") from None
+
+    if desc.scope != "service":
+        raise ValueError(
+            f"Augment '{augment_name}' has scope '{desc.scope}', "
+            f"not 'service'. Use add_workspace_augment() instead."
+        )
+
+    # Find the target service
+    svc = next((s for s in spec.services if s.name == service_name), None)
+    if svc is None:
+        raise ValueError(f"Service '{service_name}' not found in workspace spec.")
+
+    # Check for duplicates
+    existing = {a.name for a in svc.augments}
+    if augment_name in existing:
+        raise ValueError(
+            f"Augment '{augment_name}' is already present on service '{service_name}'."
+        )
+
+    # Validate target selection requirement
+    if desc.needs_target_selection:
+        targets = (options or {}).get("targets", [])
+        if not targets:
+            raise ValueError(
+                f"Augment '{augment_name}' requires target selection. "
+                f'Pass options={{"targets": [...]}}.'
+            )
+
+    _validate_augment_prerequisites(augment_name, spec, service_name=service_name)
+
+    svc.augments.append(ServiceAugment(name=augment_name, options=options or {}))
+    save_spec(spec, spec_path)
+    return spec
+
+
+def remove_service_augment(
+    output_dir: Path,
+    service_name: str,
+    augment_name: str,
+) -> ComposeSpec:
+    """Remove a service-scoped augment from a service.
+
+    Only updates the spec — scaffolded files are NOT removed (they may
+    contain user edits).  Returns the updated spec.
+    Raises ``ValueError`` if the augment is not present.
+    """
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    svc = next((s for s in spec.services if s.name == service_name), None)
+    if svc is None:
+        raise ValueError(f"Service '{service_name}' not found in workspace spec.")
+
+    original_count = len(svc.augments)
+    svc.augments = [a for a in svc.augments if a.name != augment_name]
+
+    if len(svc.augments) == original_count:
+        raise ValueError(f"Augment '{augment_name}' is not present on service '{service_name}'.")
+
+    save_spec(spec, spec_path)
+    return spec
+
+
+def available_service_augments(
+    output_dir: Path,
+    service_name: str,
+) -> list[str]:
+    """Return augment names that can be added to a service.
+
+    Filters out augments already present, those with unmet prerequisites,
+    and those with conflicts.
+    """
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    svc = next((s for s in spec.services if s.name == service_name), None)
+    if svc is None:
+        return []
+
+    existing = {a.name for a in svc.augments}
+    available: list[str] = []
+
+    for name, desc in sorted(AUGMENT_REGISTRY.items()):
+        if desc.scope != "service":
+            continue
+        if name in existing:
+            continue
+        try:
+            _validate_augment_prerequisites(name, spec, service_name=service_name)
+        except ValueError:
+            continue
+        available.append(name)
+
+    return available