ndsdk-cli 1.0.0__py3-none-any.whl

ndsdk/generators/engine.py

@@ -0,0 +1,715 @@
+"""Manifest-driven generation engine.
+
+A single generator reads a ``layout.yaml`` describing a (type, style) variant and
+emits files. New architectures are added by dropping a template folder with a
+manifest under ``templates/<type>/<style>/`` — no Python changes — unless a
+variant needs a brand-new composition step, which is added once as a *hook*.
+
+Per-service config can carry:
+
+* ``models`` / ``dtos`` / ``bos`` / ``providers`` / ``endpoints``
+* ``integrations`` — external resources such as database, storage, queue, API
+* ``packages`` — capabilities that must be injected into generated projects
+* ``providers[].methods`` — common provider method descriptors. Database methods
+  use the same common shape as storage/queue/API methods; database-specific
+  details live under method ``settings``.
+
+Selective regeneration: ``generate`` accepts a :class:`GenerationFilter` so a
+single service and/or a single layer (model, provider, service, ...) can be
+re-emitted without touching the rest of the solution.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .. import naming
+from ..config_normalizer import normalize_config
+from ..registry import PackageRegistry, flatten_appsettings, merge_appsettings,_deep_merge
+from . import base
+
+TEMPLATES_DIR = base.TEMPLATES_DIR
+
+# Stable namespace for deterministic project GUIDs (keeps the .sln stable across
+# runs and across selective regeneration).
+_GUID_NS = uuid.UUID("6f9619ff-8b86-d011-b42d-00cf4fc964ff")
+
+HEALTH_ENDPOINT = {
+    "name": "health",
+    "http_method": "GET",
+    "route": "api/v1/health",
+    "produces": "text/plain",
+    "summary": "Health check endpoint for service liveness verification.",
+    "description": "Returns a simple status response indicating the service is reachable.",
+    "is_health": True,
+}
+
+_SCOPE_KEYS = {
+    "per_model": ("models", "model"),
+    "per_dto": ("dtos", "dto"),
+    "per_provider": ("providers", "provider"),
+    "per_bo": ("bos", "bo"),
+    "per_endpoint": ("business_endpoints", "endpoint"),
+    "per_entity": ("entities", "entity"),
+}
+
+# Default layer label derived from an artifact's scope when it declares none.
+_SCOPE_DEFAULT_LAYER = {
+    "per_model": "model",
+    "per_dto": "dto",
+    "per_provider": "provider",
+    "per_bo": "bo",
+    "per_endpoint": "endpoint",
+    "per_entity": "entity",
+}
+
+
+# ----------------------------- selective regen ---------------------------- #
+@dataclass
+class GenerationFilter:
+    """Restrict a generation run to certain services and/or layers.
+
+    Empty sets mean "no restriction". When any restriction is active the engine
+    leaves the solution file and the config copy untouched, so regenerating a
+    single layer never rewrites unrelated solution structure.
+    """
+
+    services: set[str] = field(default_factory=set)
+    layers: set[str] = field(default_factory=set)
+    force: bool = False
+
+    @property
+    def active(self) -> bool:
+        return bool(self.services or self.layers)
+
+    def allow_service(self, name: str) -> bool:
+        return not self.services or name in self.services
+
+    def allow_layer(self, layer: str) -> bool:
+        return not self.layers or layer in self.layers
+
+
+# ----------------------------- discovery ---------------------------------- #
+def available_variants() -> list[tuple[str, str]]:
+    """Return all (type, style) pairs that have a layout.yaml."""
+    out = []
+    for type_dir in sorted(TEMPLATES_DIR.iterdir()):
+        if not type_dir.is_dir() or type_dir.name.startswith("_"):
+            continue
+        for style_dir in sorted(type_dir.iterdir()):
+            if (style_dir / "layout.yaml").exists():
+                out.append((type_dir.name, style_dir.name))
+    return out
+
+
+def resolve_variant(config: dict) -> tuple[str, str, Path]:
+    project = config.get("project", {})
+    ptype = project.get("type", "microservice")
+    style = project.get("architecture", "layered")
+    variant_dir = TEMPLATES_DIR / ptype / style
+    if not (variant_dir / "layout.yaml").exists():
+        opts = ", ".join(f"{t}/{s}" for t, s in available_variants()) or "(none)"
+        raise ValueError(
+            f"Unknown architecture '{ptype}/{style}'. Available: {opts}"
+        )
+    return ptype, style, variant_dir
+
+
+def get_generator(config: dict, output_dir: str) -> "Engine":
+    return Engine(config, output_dir)
+
+
+def available_layers() -> list[str]:
+    """Distinct layer labels declared across all shipped variants (for --layer)."""
+    layers: set[str] = set()
+    for ptype, style in available_variants():
+        layout = yaml.safe_load((TEMPLATES_DIR / ptype / style / "layout.yaml").read_text())
+        for proj in layout.get("projects", []):
+            for art in proj.get("artifacts", []):
+                layers.add(_artifact_layer(art))
+    return sorted(layers)
+
+
+def _artifact_layer(art: dict) -> str:
+    if art.get("layer"):
+        return art["layer"]
+    if "hook" in art:
+        return art["hook"]
+    return _SCOPE_DEFAULT_LAYER.get(art.get("scope", "once"), "once")
+
+
+# ------------------------------- engine ----------------------------------- #
+class Engine:
+    def __init__(self, config: dict, output_dir: str):
+        self.config = normalize_config(config)
+        self.project = self.config["project"]
+        self.ptype, self.style, self.variant_dir = resolve_variant(self.config)
+        self.layout = yaml.safe_load((self.variant_dir / "layout.yaml").read_text())
+
+        self.solution_name = self.project["name"]
+        self.namespace_root = self.project.get("namespace_root", "")
+        self.dotnet = self.project.get("dotnet_version", "net8.0")
+        self.version_strategy = self.project.get("nuget_version_strategy", "floating")
+        self.config_versions = self.config.get("package_versions", {})
+
+        self.output_dir = Path(output_dir)
+        self.solution_dir = self.output_dir / self.solution_name
+        self.env = base.make_env(self.variant_dir)
+        self.packages = PackageRegistry()
+        self.errors: list[str] = []
+
+    def _package_versions_for_service(self, svc: dict) -> dict:
+        root_versions = self.config.get("package_versions", {}) or {}
+        service_versions = svc.get("package_versions", {}) or {}
+
+        # Service-level version wins over root-level version.
+        return {**root_versions, **service_versions}
+
+    # ---- package + namespace resolution per service --------------------- #
+    def _service_integrations(self, svc: dict) -> dict[str, dict]:
+        return {
+            i.get("name"): i
+            for i in svc.get("integrations", []) or []
+            if isinstance(i, dict) and i.get("name")
+        }
+
+    def _service_database(self, svc: dict) -> dict | None:
+        """Resolve database settings from the common integration/provider model.
+
+        Public config no longer needs a separate `database:` block. A database is
+        just an integration whose kind is `database`, optionally referenced by a
+        provider whose kind is also `database`.
+        """
+        integrations = self._service_integrations(svc)
+        selected: dict | None = None
+
+        for prov in svc.get("providers", []) or []:
+            integration = integrations.get(prov.get("integration"))
+            kind = str(prov.get("kind") or (integration or {}).get("kind") or "custom").lower()
+            if kind == "database":
+                selected = integration
+                break
+
+        if selected is None:
+            selected = next(
+                (i for i in integrations.values() if str(i.get("kind", "")).lower() == "database"),
+                None,
+            )
+
+        # Compatibility only: if normalize_config was bypassed and an old block
+        # is still present, use it internally without exposing it as the target
+        # public config shape.
+        legacy_db = svc.get("database") if isinstance(svc.get("database"), dict) else None
+        if selected is None and legacy_db is None:
+            return None
+
+        if selected is not None:
+            settings = selected.get("settings") if isinstance(selected.get("settings"), dict) else {}
+            provider = selected.get("provider") or selected.get("store")
+            db_type = settings.get("database_type") or selected.get("database_type") or selected.get("type")
+            out = {
+                "store": provider,
+                "provider": provider,
+                "type": db_type or "non_relational",
+                "connection_string_name": settings.get("connection_string_name"),
+                "integration": selected.get("name"),
+            }
+        else:
+            out = {
+                "store": legacy_db.get("store") or legacy_db.get("provider"),
+                "provider": legacy_db.get("provider") or legacy_db.get("store"),
+                "type": legacy_db.get("type", "non_relational"),
+                "connection_string_name": legacy_db.get("connection_string_name"),
+                "integration": legacy_db.get("integration"),
+            }
+        return {k: v for k, v in out.items() if v is not None}
+
+    def _service_storage(self, svc: dict) -> dict | None:
+        """Resolve an Azure blob storage integration, if any.
+
+        Mirrors :meth:`_service_database`: a storage capability is just an
+        integration whose kind is ``storage`` (optionally referenced by a
+        provider whose kind is ``storage``). Returns the connection-string name
+        and container so the file-storage package can be auto-wired.
+        """
+        integrations = self._service_integrations(svc)
+        selected: dict | None = None
+
+        for prov in svc.get("providers", []) or []:
+            integration = integrations.get(prov.get("integration"))
+            kind = str(prov.get("kind") or (integration or {}).get("kind") or "custom").lower()
+            if kind == "storage":
+                selected = integration
+                break
+        if selected is None:
+            selected = next(
+                (i for i in integrations.values() if str(i.get("kind", "")).lower() == "storage"),
+                None,
+            )
+        if selected is None:
+            return None
+
+        settings = selected.get("settings") if isinstance(selected.get("settings"), dict) else {}
+        out = {
+            "provider": selected.get("provider"),
+            "connection_string_name": settings.get("connection_string_name"),
+            "container_name": settings.get("container_name"),
+            "integration": selected.get("name"),
+        }
+        return {k: v for k, v in out.items() if v is not None}
+
+    def _resolve_packages(self, svc: dict):
+        defaults = self.config.get("defaults", {}).get("packages", {}) or {}
+        service_packages = svc.get("packages", {}) or {}
+
+        merged = _deep_merge(defaults, service_packages)
+
+        # A service that declares a database integration/provider implicitly turns
+        # on the db_provider package and feeds it connection settings, unless the
+        # package is explicitly disabled.
+        db = self._service_database(svc)
+        if db and "db_provider" in self.packages.available():
+            existing = merged.get("db_provider")
+            if not isinstance(existing, dict) or existing.get("enabled") is not False:
+                pkg_cfg = dict(existing) if isinstance(existing, dict) else {}
+                pkg_cfg.setdefault("enabled", True)
+                pkg_cfg.setdefault("db_type", db.get("type"))
+                if db.get("store"):
+                    pkg_cfg.setdefault("provider", db["store"])
+                if db.get("connection_string_name"):
+                    pkg_cfg.setdefault("connection_string_name", db["connection_string_name"])
+                merged["db_provider"] = pkg_cfg
+
+        # A service that declares a storage integration/provider implicitly turns
+        # on the Azure file-storage package, unless explicitly disabled.
+        storage = self._service_storage(svc)
+        if storage and "file_storage_azure" in self.packages.available():
+            existing = merged.get("file_storage_azure")
+            if not isinstance(existing, dict) or existing.get("enabled") is not False:
+                pkg_cfg = dict(existing) if isinstance(existing, dict) else {}
+                pkg_cfg.setdefault("enabled", True)
+                merged["file_storage_azure"] = pkg_cfg
+
+        return self.packages.resolve_enabled(merged)
+
+    def _service_base_ns(self, svc: dict) -> str:
+        return naming.namespace(self.namespace_root, svc["name"])
+
+    # ---- database adapter resolution (configurable per store) ----------- #
+    _STORE_KEY_ALIASES = {
+        "sqlserver": "mssql",
+        "sql_server": "mssql",
+        "mssql": "mssql",
+        "postgres": "postgres",
+        "postgresql": "postgres",
+        "cassandra": "cassandra",
+    }
+
+    @classmethod
+    def _normalize_store_key(cls, store: str) -> str:
+        key = str(store or "").strip().lower().replace("-", "_")
+        return cls._STORE_KEY_ALIASES.get(key, key)
+
+    def _resolve_db_adapter(self, db_settings: dict | None, database: dict | None) -> dict:
+        """Pick the adapter descriptor for the service's store.
+
+        Adapters live in the db_provider package config (``adapters:``) so a new
+        engine is added by editing config, not Python. Resolution order:
+        exact store key -> relational_default / non_relational_default by type.
+        """
+        adapters = (db_settings or {}).get("adapters", {}) or {}
+        store = (database or {}).get("store") or (database or {}).get("provider") \
+            or (db_settings or {}).get("provider") or ""
+        db_type = (database or {}).get("type") or (db_settings or {}).get("db_type") or "non_relational"
+
+        key = self._normalize_store_key(store)
+        adapter = adapters.get(key)
+        if not isinstance(adapter, dict):
+            fallback = "relational_default" if db_type == "relational" else "non_relational_default"
+            adapter = adapters.get(fallback)
+        adapter = dict(adapter) if isinstance(adapter, dict) else {}
+        adapter.setdefault(
+            "dbtype_enum_value", "Relational" if db_type == "relational" else "NonRelational"
+        )
+        return adapter
+
+    def _base_context(self, svc: dict) -> dict:
+        resolved = self._resolve_packages(svc)
+        obs = next((s for p, s in resolved if p.key == "observability"), None)
+        db_pkg, db_settings = next(
+            ((p, s) for p, s in resolved if p.key == "db_provider"), (None, None)
+        )
+        database = self._service_database(svc)
+        endpoints = [HEALTH_ENDPOINT] + svc.get("endpoints", [])
+        ns = base.resolve_namespaces(self.layout.get("namespaces", {}), self._service_base_ns(svc))
+
+        # Resolve the database adapter (by store, configurable) and expose the
+        # runtime schema-config key + facade response type on db_settings, so the
+        # DI fragment and provider templates stay declarative. Mutated in place
+        # because the same dict is what the Program.cs fragment receives.
+        response_type = "ExternalizationResponse"
+        if isinstance(db_settings, dict):
+            adapter = self._resolve_db_adapter(db_settings, database)
+            db_settings["adapter"] = adapter
+            relational_cfg = db_settings.get("relational") if isinstance(db_settings.get("relational"), dict) else {}
+            db_settings["schema_config_key"] = (
+                relational_cfg.get("schema_name_config_key")
+                or "DB_Provider:RelationalDatabase:SqlServer:SchemaName"
+            )
+            response_type = db_settings.setdefault("response_type", response_type)
+
+        # Normalise providers so templates have a stable, provider-agnostic
+        # shape. Provider kind, not the presence of methods, decides behaviour.
+        integrations = self._service_integrations(svc)
+        providers = []
+        for p in svc.get("providers", []):
+            p = dict(p)
+            integration = integrations.get(p.get("integration"))
+            provider_kind = str(p.get("kind") or (integration or {}).get("kind") or "custom").lower()
+            p["kind"] = provider_kind
+            if integration and integration.get("provider") and not p.get("provider"):
+                p["provider"] = integration["provider"]
+            methods = p.get("methods", []) or []
+            p["methods"] = [self._normalise_method(m, provider_kind, database) for m in methods]
+            # For relational (stored-procedure) methods the first cut returns the
+            # facade response verbatim; the configured `returns` is kept for the
+            # later mapping layer but does not drive the signature.
+            for m in p["methods"]:
+                m["return_type_cs"] = (
+                    response_type if m.get("relational")
+                    else naming.csharp_type(m.get("returns") or "object")
+                )
+            p["has_methods"] = bool(p["methods"])
+            p["has_relational"] = any(m.get("relational") for m in p["methods"])
+            p["is_db"] = provider_kind == "database"
+            providers.append(p)
+
+        return {
+            "config": self.config,
+            "project": self.project,
+            "svc": svc,
+            "service_name": svc["name"],
+            "service": svc["name"],
+            "dotnet": self.dotnet,
+            "ns": ns,
+            "endpoints": endpoints,
+            "business_endpoints": [e for e in endpoints if not e.get("is_health")],
+            "models": svc.get("models", []),
+            "dtos": svc.get("dtos", []),
+            "entities": svc.get("entities", []),
+            "bos": svc.get("bos", []),
+            "providers": providers,
+            "db_providers": [p for p in providers if p["is_db"]],
+            "database": database,
+            "db_enabled": database is not None,
+            "db_settings": db_settings or {},
+            "resolved_packages": resolved,
+            "obs": obs,
+            "obs_enabled": obs is not None,
+            "controller_style": self.layout.get("controller_style", "service_manager"),
+            "use_service_locator": self.layout.get("controller_style", "service_manager") == "service_manager",
+        }
+
+    @staticmethod
+    def _normalise_method(method: dict, provider_kind: str, database: dict | None) -> dict:
+        m = dict(method)
+        settings = dict(m.get("settings") or {})
+        if isinstance(m.get("database"), dict):
+            settings = {**m["database"], **settings}
+
+        # Backward-compatible aliases are consumed into the common method shape.
+        for key in ("stored_procedure", "target", "table", "inputs", "parameters", "cursors"):
+            if key in m and key not in settings:
+                settings[key] = m[key]
+
+        input_entity = m.get("input_entity") or m.get("entity")
+        output_entity = m.get("output_entity")
+
+        m["input_entity"] = input_entity
+        m["entity"] = input_entity  # internal template convenience only
+        m["output_entity"] = output_entity
+        m["settings"] = settings
+
+        if not m.get("returns"):
+            m["returns"] = output_entity or "object"
+
+        op = str(m.get("operation") or "").strip().replace("-", "_").replace(" ", "_").lower()
+        if op in {"storedprocedure", "stored_proc", "sp"}:
+            op = "stored_procedure"
+        elif op in {"getresults", "get_results"}:
+            op = "query"
+        elif not op and provider_kind == "database":
+            op = "stored_procedure" if settings.get("stored_procedure") else "query"
+        m["operation"] = op or m.get("operation") or "execute"
+
+        if provider_kind == "database":
+            default_db_type = (database or {}).get("type", "non_relational")
+            method_kind = settings.get("method_type") or m.get("kind")
+            if method_kind not in {"relational", "non_relational"}:
+                method_kind = "relational" if m["operation"] == "stored_procedure" else default_db_type
+            if method_kind not in {"relational", "non_relational"}:
+                method_kind = "non_relational"
+
+            m["kind"] = method_kind
+            m["relational"] = method_kind == "relational"
+            m["db_type_enum"] = "Relational" if method_kind == "relational" else "NonRelational"
+            m["facade_operation"] = "StoredProcedure" if m["operation"] == "stored_procedure" or method_kind == "relational" else "Query"
+            m["target"] = settings.get("target") or settings.get("stored_procedure") or m.get("target") or (m.get("name") if method_kind == "relational" else "GetResults")
+            m["stored_procedure"] = settings.get("stored_procedure") or (m["target"] if method_kind == "relational" else None)
+            m["table"] = settings.get("table")
+            m["inputs"] = settings.get("inputs", []) or []
+            m["parameters"] = settings.get("parameters", []) or []
+            # Non-relational extras (Cassandra-style facade requests).
+            # extended_context_action -> emits ExtendedContext = new CassandraExtendedContext { Action = "insert"|"update" }
+            m["extended_context_action"] = settings.get("extended_context_action")
+            m["extended_context_type"] = settings.get("extended_context_type", "CassandraExtendedContext")
+        else:
+            m["kind"] = provider_kind
+            m["relational"] = False
+            m.setdefault("inputs", [])
+            m.setdefault("parameters", [])
+
+        return m
+
+    # ---- generation ----------------------------------------------------- #
+    def generate(self, filter: GenerationFilter | None = None) -> list[Path]:
+        flt = filter or GenerationFilter()
+        written: list[Path] = []
+        self.solution_dir.mkdir(parents=True, exist_ok=True)
+        sln_projects: list[dict] = []
+        # Collect per-artifact failures instead of letting the first one abort
+        # the whole run. A bad provider template must never cost you DTOs,
+        # entities or models that are generated independently of it.
+        self.errors: list[str] = []
+
+        for svc in self.config.get("services", []):
+            if not flt.allow_service(svc["name"]):
+                continue
+            ctx = self._base_context(svc)
+            for proj in self.layout["projects"]:
+                paths, sln_entry = self._generate_project(svc, proj, ctx, flt)
+                written += paths
+                sln_projects.append(sln_entry)
+
+        # Don't rewrite solution-level files during a filtered (partial) run.
+        if not flt.active:
+            written.append(self._write_solution(sln_projects))
+            written.append(self._write_config_copy())
+
+        if self.errors:
+            # Everything that could be written has been written; surface the
+            # failures together so the user sees which artifacts need attention
+            # rather than a single traceback that hid the rest.
+            summary = "\n".join(f"  - {e}" for e in self.errors)
+            raise RuntimeError(
+                f"{len(self.errors)} artifact(s) failed to generate "
+                f"(the rest were still written):\n{summary}"
+            )
+        return written
+
+    def _project_dir(self, svc, proj) -> Path:
+        rel = proj["dir"].format(service=svc["name"], ns=self._service_base_ns(svc))
+        return self.solution_dir / rel
+
+    def _generate_project(self, svc, proj, base_ctx, flt) -> tuple[list[Path], dict]:
+        pdir = self._project_dir(svc, proj)
+        proj_ns = proj["namespace"].format(ns=self._service_base_ns(svc))
+        is_host = proj.get("host", False)
+
+        # project-to-project references
+        refs = []
+        for ref_id in proj.get("references", []):
+            ref_proj = next(p for p in self.layout["projects"] if p["id"] == ref_id)
+            ref_dir = self._project_dir(svc, ref_proj)
+            ref_name = ref_proj["csproj"]["path"].format(
+                service=svc["name"], ns=self._service_base_ns(svc)
+            )
+            rel = os.path.relpath(ref_dir / ref_name, start=pdir)
+            refs.append({"path": rel.replace("/", "\\")})
+
+        # nuget for this project
+        nuget_inputs = list(proj.get("nuget", []))
+        has_provider_artifacts = any(
+            art.get("template") in {"Provider.cs.j2", "DbProviderBase.cs.j2", "ProviderBase.cs.j2"}
+            for art in proj.get("artifacts", [])
+        )
+        if is_host or has_provider_artifacts:
+            for pkg, _ in base_ctx["resolved_packages"]:
+                # Host projects need package NuGets for DI fragments. Provider
+                # projects need package NuGets for any generated/provider-specific
+                # scaffolds, not only database scaffolds.
+                nuget_inputs += [{"name": r.name, "version": r.version} for r in pkg.nuget]
+        if is_host:
+            nuget_inputs += self.config.get("defaults", {}).get("nuget", [])
+            nuget_inputs += svc.get("nuget", [])
+        nuget_refs = base.resolve_nuget_refs(
+            nuget_inputs,
+            config_versions=self._package_versions_for_service(svc),
+            version_strategy=self.version_strategy,
+        )
+
+        proj_ctx = dict(base_ctx)
+        proj_ctx.update({
+            "project_namespace": proj_ns,
+            "project_id": proj["id"],
+            "is_host": is_host,
+            "project_references": refs,
+            "nuget_refs": nuget_refs,
+        })
+
+        # deterministic GUID from solution + project path
+        guid = str(uuid.uuid5(_GUID_NS, f"{self.solution_name}/{proj_ns}")).upper()
+
+        csproj = proj["csproj"]
+        csproj_name = csproj["path"].format(service=svc["name"], ns=self._service_base_ns(svc))
+
+        written: list[Path] = []
+        # csproj counts as the "project" layer; skip on a filtered layer run that
+        # excludes it (but never skip on a service-only filter).
+        if flt.allow_layer("csproj"):
+            content = self.env.get_template(csproj["template"]).render(**proj_ctx)
+            path, _ = base.write_file(pdir / csproj_name, content)
+            written.append(path)
+
+        for art in proj.get("artifacts", []):
+            layer = _artifact_layer(art)
+            if not flt.allow_layer(layer):
+                continue
+            try:
+                written += self._generate_artifact(svc, pdir, art, proj_ctx, flt)
+            except Exception as exc:  # noqa: BLE001 - isolate one artifact's failure
+                label = art.get("template") or art.get("hook") or layer
+                getattr(self, "errors", self.__dict__.setdefault("errors", [])).append(
+                    f"{svc['name']} / {label} ({layer}): {type(exc).__name__}: {exc}"
+                )
+
+        sln_entry = {
+            "name": csproj_name.rsplit(".", 1)[0] if csproj_name.endswith(".csproj") else csproj_name,
+            "path": str((pdir.relative_to(self.solution_dir)) / csproj_name).replace("/", "\\"),
+            "guid": guid,
+        }
+        return written, sln_entry
+
+    def _generate_artifact(self, svc, pdir, art, proj_ctx, flt) -> list[Path]:
+        scope = art.get("scope", "once")
+        owner = art.get("owner", "framework")
+        # Selective regen with --force overwrites write-once (user) files too.
+        if owner == "user" and flt.force:
+            owner = "framework"
+
+        if scope == "once":
+            loop_items = [None]
+        else:
+            collection_key, _ = _SCOPE_KEYS[scope]
+            loop_items = proj_ctx[collection_key]
+
+        written = []
+        for item in loop_items:
+            ctx = dict(proj_ctx)
+            fmt = {"service": svc["name"], "ns": proj_ctx["ns"]["base"]}
+            if scope != "once":
+                _, var_name = _SCOPE_KEYS[scope]
+                ctx[var_name] = item
+                fmt[var_name] = item.get("name", "") if isinstance(item, dict) else item
+
+            # per-provider artifacts that gate on db-only providers
+            if art.get("only") == "db_provider" and not (isinstance(item, dict) and item.get("is_db")):
+                continue
+
+            out_path = pdir / art["path"].format(**fmt)
+
+            if "hook" in art:
+                content = self._run_hook(art["hook"], ctx)
+            else:
+                content = self.env.get_template(art["template"]).render(**ctx)
+
+            path, _ = base.write_file(out_path, content, owner=owner)
+            written.append(path)
+        return written
+
+    # ---- hooks (the only place a new building block needs Python) ------- #
+    def _run_hook(self, name: str, ctx: dict) -> str:
+        if name == "program":
+            return self._hook_program(ctx)
+        if name == "appsettings":
+            return self._hook_appsettings(ctx)
+        if name == "launch":
+            return self._hook_launch(ctx)
+        raise ValueError(f"Unknown manifest hook '{name}'")
+
+    def _hook_program(self, ctx: dict) -> str:
+        fragments = []
+        app_fragments = []
+        for pkg, settings in ctx["resolved_packages"]:
+            if pkg.program_fragment:
+                rendered = self.env.from_string(pkg.program_fragment).render(
+                    settings=settings, **ctx
+                ).strip()
+                if rendered:
+                    fragments.append(f"// --- {pkg.display_name} ---\n{rendered}")
+            if pkg.app_fragment:
+                rendered = self.env.from_string(pkg.app_fragment).render(
+                    settings=settings, **ctx
+                ).strip()
+                if rendered:
+                    app_fragments.append(f"// --- {pkg.display_name} ---\n{rendered}")
+        return self.env.get_template("Program.cs.j2").render(
+            package_registrations=fragments,
+            app_registrations=app_fragments,
+            **ctx,
+        )
+
+    def _merged_appsettings(self, ctx: dict) -> dict:
+        """Build the fully-merged appsettings dict for a service.
+
+        Used both to render ``appsettings.json`` and to project every setting
+        into ``launchSettings.json`` as ``__``-nested environment variables.
+        """
+        out = {
+            "ServiceName": ctx["service_name"],
+            "Logging": {"LogLevel": {"Default": "Information", "Microsoft.AspNetCore": "Warning"}},
+            "AllowedHosts": "*",
+        }
+        out = merge_appsettings(out, json.dumps(ctx["svc"].get("appsettings", {})))
+        for pkg, settings in ctx["resolved_packages"]:
+            if pkg.appsettings_fragment:
+                frag = self.env.from_string(pkg.appsettings_fragment).render(settings=settings, **ctx)
+                if frag.strip():
+                    out = merge_appsettings(out, frag)
+        return out
+
+    def _hook_appsettings(self, ctx: dict) -> str:
+        return json.dumps(self._merged_appsettings(ctx), indent=2)
+
+    def _hook_launch(self, ctx: dict) -> str:
+        """Render launchSettings.json with every appsetting mirrored into the
+        profile's ``environmentVariables`` using the .NET ``__`` hierarchy
+        separator, so a developer running locally gets the same configuration
+        the app would read from appsettings without editing JSON by hand."""
+        merged = self._merged_appsettings(ctx)
+        env_vars = {"ASPNETCORE_ENVIRONMENT": "Development"}
+        env_vars.update(flatten_appsettings(merged))
+        launch_ctx = dict(ctx)
+        launch_ctx["launch_env_vars"] = env_vars
+        return self.env.get_template("launchSettings.json.j2").render(**launch_ctx)
+
+    # ---- solution + config copy ----------------------------------------- #
+    def _write_solution(self, projects: list[dict]) -> Path:
+        content = self.env.get_template(
+            self.layout.get("solution", {}).get("template", "Solution.sln.j2")
+        ).render(projects=projects, config=self.config)
+        path, _ = base.write_file(self.solution_dir / f"{self.solution_name}.sln", content)
+        return path
+
+    def _write_config_copy(self) -> Path:
+        path, _ = base.write_file(
+            self.solution_dir / "nd-config.yaml",
+            yaml.dump(self.config, sort_keys=False, indent=2),
+        )
+        return path