scaffold-ca-python 0.1.1__py3-none-any.whl

scaffold_ca_python/models/layer.py

@@ -0,0 +1,41 @@
+"""Layer enum and FORBIDDEN_IMPORTS dependency mapping (T013)."""
+
+from enum import StrEnum
+
+
+class Layer(StrEnum):
+    DOMAIN_MODEL = "domain/model"
+    DOMAIN_USECASE = "domain/usecase"
+    ENTRY_POINTS = "infrastructure/entry-points"
+    DRIVEN_ADAPTERS = "infrastructure/driven-adapters"
+    HELPERS = "infrastructure/helpers"
+    APPLICATION = "application"
+
+
+# Maps each inner layer to the set of outer layers it must NOT import from.
+# Layers not present as keys (APPLICATION) may import from any layer.
+FORBIDDEN_IMPORTS: dict[Layer, list[Layer]] = {
+    Layer.DOMAIN_MODEL: [
+        Layer.DOMAIN_USECASE,
+        Layer.ENTRY_POINTS,
+        Layer.DRIVEN_ADAPTERS,
+        Layer.HELPERS,
+        Layer.APPLICATION,
+    ],
+    Layer.DOMAIN_USECASE: [
+        Layer.ENTRY_POINTS,
+        Layer.DRIVEN_ADAPTERS,
+        Layer.HELPERS,
+        Layer.APPLICATION,
+    ],
+    Layer.ENTRY_POINTS: [
+        Layer.APPLICATION,
+    ],
+    Layer.DRIVEN_ADAPTERS: [
+        Layer.APPLICATION,
+    ],
+    Layer.HELPERS: [
+        Layer.APPLICATION,
+    ],
+    Layer.APPLICATION: [],
+}

scaffold_ca_python/models/violation.py

@@ -0,0 +1,26 @@
+"""Violation and ValidationReport Pydantic v2 models (T016)."""
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from scaffold_ca_python.models.layer import Layer
+
+
+class Violation(BaseModel):
+    source_file: Path
+    line_number: int
+    import_statement: str
+    source_layer: Layer
+    target_layer: Layer
+    resolution_hint: str
+
+
+class ValidationReport(BaseModel):
+    project_root: Path
+    files_scanned: int
+    violations: list[Violation]
+
+    @property
+    def passed(self) -> bool:
+        return len(self.violations) == 0

scaffold_ca_python/templates/driven_adapter/generic/__init__.py.jinja2

@@ -0,0 +1 @@
+"""{{ class_name }} adapter package."""

scaffold_ca_python/templates/driven_adapter/generic/adapter.py.jinja2

@@ -0,0 +1,18 @@
+"""{{ class_name }} async driven adapter."""
+
+from __future__ import annotations
+
+
+class {{ class_name }}Adapter:
+    """Async driven adapter for {{ class_name }}.
+
+    Implement the methods below to integrate with your external resource.
+    """
+
+    async def execute(self) -> None:
+        """Perform the adapter's primary operation.
+
+        Raises:
+            NotImplementedError: Replace with the concrete implementation.
+        """
+        raise NotImplementedError

scaffold_ca_python/templates/driven_adapter/generic/test_adapter.py.jinja2

@@ -0,0 +1,22 @@
+"""Tests for {{ class_name }}Adapter."""
+
+from __future__ import annotations
+
+import pytest
+
+from {{ project.python_package }}.infrastructure.driven_adapters.{{ module_name }}.{{ module_name }}_adapter import (
+    {{ class_name }}Adapter,
+)
+
+
+@pytest.fixture()
+def adapter() -> {{ class_name }}Adapter:
+    return {{ class_name }}Adapter()
+
+
+@pytest.mark.asyncio
+async def test_{{ module_name }}_adapter_execute_raises_not_implemented(
+    adapter: {{ class_name }}Adapter,
+) -> None:
+    with pytest.raises(NotImplementedError):
+        await adapter.execute()

scaffold_ca_python/templates/driven_adapter/rest_consumer/__init__.py.jinja2

@@ -0,0 +1 @@
+"""REST consumer driven adapter package."""

scaffold_ca_python/templates/driven_adapter/rest_consumer/rest_consumer.py.jinja2

@@ -0,0 +1,27 @@
+"""Async HTTP client adapter using httpx."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class RestConsumerAdapter:
+    """Async REST consumer adapter.
+
+    Wraps :class:`httpx.AsyncClient` to provide a thin, testable HTTP boundary.
+    Replace the placeholder methods with your actual API calls.
+    """
+
+    def __init__(self, base_url: str = "", timeout: float = 10.0) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+
+    async def get(self, path: str, **kwargs: object) -> httpx.Response:
+        """Perform an async GET request."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as client:
+            return await client.get(path, **kwargs)
+
+    async def post(self, path: str, **kwargs: object) -> httpx.Response:
+        """Perform an async POST request."""
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout) as client:
+            return await client.post(path, **kwargs)

scaffold_ca_python/templates/driven_adapter/rest_consumer/test_rest_consumer.py.jinja2

@@ -0,0 +1,24 @@
+"""Tests for RestConsumerAdapter."""
+
+from __future__ import annotations
+
+import pytest
+import respx
+import httpx
+
+from {{ project.python_package }}.infrastructure.driven_adapters.rest_consumer.rest_consumer import (
+    RestConsumerAdapter,
+)
+
+
+@pytest.fixture()
+def adapter() -> RestConsumerAdapter:
+    return RestConsumerAdapter(base_url="https://example.com")
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_get_returns_response(adapter: RestConsumerAdapter) -> None:
+    respx.get("https://example.com/ping").mock(return_value=httpx.Response(200))
+    response = await adapter.get("/ping")
+    assert response.status_code == 200

scaffold_ca_python/templates/driven_adapter/secrets/__init__.py.jinja2

@@ -0,0 +1 @@
+"""Secrets adapter package."""

scaffold_ca_python/templates/driven_adapter/secrets/secrets_adapter.py.jinja2

@@ -0,0 +1,37 @@
+"""Async secrets-store adapter (provider-agnostic interface)."""
+
+from __future__ import annotations
+
+
+class SecretsAdapter:
+    """Fetches secrets from an external secrets store.
+
+    Replace the body of :meth:`get_secret` with the call to your actual
+    provider (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, etc.).
+    """
+
+    async def get_secret(self, secret_name: str) -> str:
+        """Return the value of a named secret.
+
+        Args:
+            secret_name: Provider-specific identifier of the secret.
+
+        Returns:
+            The secret value as a plain string.
+
+        Raises:
+            NotImplementedError: Until the concrete provider is wired in.
+        """
+        raise NotImplementedError(f"Provider not configured for secret '{secret_name}'.")
+
+    async def set_secret(self, secret_name: str, value: str) -> None:
+        """Write or update a named secret.
+
+        Args:
+            secret_name: Provider-specific identifier of the secret.
+            value: The new secret value.
+
+        Raises:
+            NotImplementedError: Until the concrete provider is wired in.
+        """
+        raise NotImplementedError(f"Provider not configured for secret '{secret_name}'.")

scaffold_ca_python/templates/driven_adapter/secrets/test_secrets_adapter.py.jinja2

@@ -0,0 +1,26 @@
+"""Tests for SecretsAdapter."""
+
+from __future__ import annotations
+
+import pytest
+
+from {{ project.python_package }}.infrastructure.driven_adapters.secrets.secrets_adapter import (
+    SecretsAdapter,
+)
+
+
+@pytest.fixture()
+def adapter() -> SecretsAdapter:
+    return SecretsAdapter()
+
+
+@pytest.mark.asyncio
+async def test_get_secret_raises_not_implemented(adapter: SecretsAdapter) -> None:
+    with pytest.raises(NotImplementedError):
+        await adapter.get_secret("my-secret")
+
+
+@pytest.mark.asyncio
+async def test_set_secret_raises_not_implemented(adapter: SecretsAdapter) -> None:
+    with pytest.raises(NotImplementedError):
+        await adapter.set_secret("my-secret", "value")

scaffold_ca_python/templates/entry_point/agent/__init__.py.jinja2

@@ -0,0 +1 @@
+"""Agent entry-point package."""

scaffold_ca_python/templates/entry_point/agent/agent.py.jinja2

@@ -0,0 +1,49 @@
+"""A2A async agent handler stub."""
+
+from __future__ import annotations
+
+{% if enable_kafka %}
+# Kafka consumer stub — replace with your actual broker configuration.
+# from aiokafka import AIOKafkaConsumer
+{% endif %}
+{% if enable_mcp_client %}
+# MCP tool-call client stub — replace with your actual MCP client.
+# from mcp import ClientSession
+{% endif %}
+
+
+class {{ project.name }}Agent:
+    """Agent-to-Agent (A2A) protocol handler for {{ project.name }}.
+
+    Implement :meth:`run` to handle incoming agent task requests.
+    """
+
+{% if enable_kafka %}
+    async def consume(self, topic: str) -> None:
+        """Consume messages from a Kafka topic."""
+        # consumer = AIOKafkaConsumer(topic, bootstrap_servers="localhost:9092")
+        # await consumer.start()
+        raise NotImplementedError("Wire in your Kafka consumer here.")
+
+{% endif %}
+{% if enable_mcp_client %}
+    async def call_tool(self, tool_name: str, arguments: dict[str, object]) -> object:
+        """Invoke a tool via the MCP client."""
+        # async with ClientSession(...) as session:
+        #     return await session.call_tool(tool_name, arguments)
+        raise NotImplementedError("Wire in your MCP client here.")
+
+{% endif %}
+    async def run(self, task: dict[str, object]) -> dict[str, object]:
+        """Handle an incoming A2A task.
+
+        Args:
+            task: The incoming task payload.
+
+        Returns:
+            The agent response payload.
+
+        Raises:
+            NotImplementedError: Replace with your task handling logic.
+        """
+        raise NotImplementedError

scaffold_ca_python/templates/entry_point/agent/card.py.jinja2

@@ -0,0 +1,15 @@
+"""AgentCard definition for {{ project.name }}."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AgentCard:
+    """Describes the capabilities and identity of this agent."""
+
+    name: str = "{{ project.name }}"
+    description: str = "An AI agent built with scaffold-ca-python."
+    version: str = "0.1.0"
+    capabilities: list[str] = field(default_factory=list)

scaffold_ca_python/templates/entry_point/agent/entrypoint_main.py.jinja2

@@ -0,0 +1,13 @@
+"""{{ name }} agent entrypoint."""
+import asyncio
+
+from {{ python_package }}.infrastructure.entry_points.agent.agent import run
+
+
+def main() -> None:
+    """Start the agent runner."""
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

scaffold_ca_python/templates/entry_point/agent/test_agent.py.jinja2

@@ -0,0 +1,20 @@
+"""Tests for {{ project.name }}Agent."""
+
+from __future__ import annotations
+
+import pytest
+
+from {{ project.python_package }}.infrastructure.entry_points.agent.agent import {{ project.name }}Agent
+from {{ project.python_package }}.infrastructure.entry_points.agent.card import AgentCard
+
+
+def test_agent_card_has_name() -> None:
+    card = AgentCard()
+    assert card.name == "{{ project.name }}"
+
+
+@pytest.mark.asyncio
+async def test_agent_run_raises_not_implemented() -> None:
+    agent = {{ project.name }}Agent()
+    with pytest.raises(NotImplementedError):
+        await agent.run({})

scaffold_ca_python/templates/entry_point/generic/__init__.py.jinja2

@@ -0,0 +1 @@
+"""Generic entry-point package."""

scaffold_ca_python/templates/entry_point/generic/entrypoint_main.py.jinja2

@@ -0,0 +1,13 @@
+"""{{ name }} generic entrypoint."""
+import asyncio
+
+from {{ project.python_package }}.infrastructure.entry_points.generic.entry_point import run
+
+
+def main() -> None:
+    """Run the generic handler."""
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

scaffold_ca_python/templates/entry_point/generic/handler.py.jinja2

@@ -0,0 +1,13 @@
+"""Generic async entry-point handler for {{ project.name }}."""
+
+from __future__ import annotations
+
+class EntryPoint:
+    """Generic async entry point.
+
+    Replace the body of :meth:`run` with your actual startup / handler logic.
+    """
+
+    async def run(self) -> None:
+        """Start the entry-point processing loop."""
+        print("Hello from the generic entry point! Replace this with your actual logic.")

scaffold_ca_python/templates/entry_point/generic/test_handler.py.jinja2

@@ -0,0 +1,35 @@
+"""Tests for the generic entry point."""
+
+from __future__ import annotations
+
+import pytest
+
+from {{ project.python_package }}.infrastructure.entry_points.generic.entry_point import EntryPoint
+
+
+class TestEntryPointRun:
+    """Test EntryPoint.run() behavior."""
+
+    @pytest.mark.asyncio
+    async def test_entry_point_run_is_async(self) -> None:
+        """Test that run method is async and callable."""
+        ep = EntryPoint()
+        result = await ep.run()
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_entry_point_run_prints_message(self, capsys: pytest.CaptureFixture[str]) -> None:
+        """Test that run method prints the placeholder message."""
+        ep = EntryPoint()
+        await ep.run()
+        captured = capsys.readouterr()
+        assert "Hello from the generic entry point" in captured.out
+
+    @pytest.mark.asyncio
+    async def test_entry_point_run_does_not_raise_exception(self) -> None:
+        """Test that run method executes without raising exceptions."""
+        ep = EntryPoint()
+        try:
+            await ep.run()
+        except Exception as exc:
+            pytest.fail(f"EntryPoint.run() raised {type(exc).__name__}: {exc}")

scaffold_ca_python/templates/entry_point/mcp/__init__.py.jinja2

@@ -0,0 +1 @@
+"""MCP server entry-point package."""

scaffold_ca_python/templates/entry_point/mcp/app.py.jinja2

@@ -0,0 +1,51 @@
+"""MCP composition root — creates the FastMCP instance and Starlette ASGI app."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from {{ project.python_package }}.application.config.container import Container
+from {{ project.python_package }}.infrastructure.entry_points.mcp_server import tools
+{% if with_resources %}from {{ project.python_package }}.infrastructure.entry_points.mcp_server import resources
+{% endif %}{% if with_prompts %}from {{ project.python_package }}.infrastructure.entry_points.mcp_server import prompts
+{% endif %}
+
+mcp: FastMCP = FastMCP("{{ project.name }}", stateless_http=True)
+
+
+@asynccontextmanager
+async def lifespan(_app: Starlette) -> None:
+    """Wire the DI container, register all MCP primitives, then run the server."""
+    container = Container()
+    container.wire(
+        modules=[
+            tools,
+            {% if with_resources %}resources,{% endif %}
+            {% if with_prompts %}prompts,{% endif %}
+        ]
+    )
+
+    await tools.bind_tools(mcp)
+    {% if with_resources %}await resources.bind_resources(mcp)
+    {% endif %}{% if with_prompts %}await prompts.bind_prompts(mcp){% endif %}
+
+    # Uncomment the following lines if you have async resources to initialize on startup and shutdown
+    #await container.resource_container.init_resources()
+
+    async with mcp.session_manager.run():
+        yield
+
+    # Uncomment the following lines if you have async resources to initialize on startup and shutdown
+    #await container.resource_container.shutdown_resources()
+
+
+def start_server() -> Starlette:
+    """Return a Starlette ASGI application wrapping the FastMCP instance."""
+    return Starlette(
+        routes=[Mount("/", app=mcp.streamable_http_app())],
+        lifespan=lifespan,
+    )

scaffold_ca_python/templates/entry_point/mcp/prompts.py.jinja2

@@ -0,0 +1,22 @@
+"""MCP prompts binding — register FastMCP prompts via dependency injection."""
+
+from __future__ import annotations
+
+from dependency_injector.wiring import Provide, inject
+from mcp.server.fastmcp import FastMCP
+
+from {{ project.python_package }}.application.config.container import Container
+
+
+@inject
+async def bind_prompts(
+    mcp: FastMCP,
+    # Replace with your actual use-case injection:
+    # prompt_usecase: SomeUseCase = Provide[Container.some_usecase],
+) -> None:
+    """Bind all MCP prompts to the server instance."""
+
+    @mcp.prompt()
+    async def example_prompt(topic: str) -> str:
+        """Example prompt stub — replace with your implementation."""
+        return f"You are an expert on {topic}. Answer concisely."

scaffold_ca_python/templates/entry_point/mcp/resources.py.jinja2

@@ -0,0 +1,22 @@
+"""MCP resources binding — register FastMCP resources via dependency injection."""
+
+from __future__ import annotations
+
+from dependency_injector.wiring import Provide, inject
+from mcp.server.fastmcp import FastMCP
+
+from {{ project.python_package }}.application.config.container import Container
+
+
+@inject
+async def bind_resources(
+    mcp: FastMCP,
+    # Replace with your actual use-case injection:
+    # some_usecase: SomeUseCase = Provide[Container.usecase_container.some_usecase],
+) -> None:
+    """Bind all MCP resources to the server instance."""
+
+    @mcp.resource("file://example_resource", mime_type="application/json")
+    async def example_resource() -> dict[str, object]:
+        """Example resource stub — replace with your implementation."""
+        return {"message": "example resource data"}

scaffold_ca_python/templates/entry_point/mcp/server.py.jinja2

@@ -0,0 +1,27 @@
+"""MCP server entrypoint — run with ``<pkg>-server`` or ``python -m <pkg>.server``."""
+
+from __future__ import annotations
+
+import sys
+
+import uvicorn
+
+from {{ project.python_package }}.application.config.config import settings
+from {{ project.python_package }}.application import app
+
+
+def main() -> None:
+    """Start the MCP server via uvicorn.
+
+    The ASGI app is obtained from :func:`app.start_server` which wires the DI
+    container and mounts the FastMCP ``streamable_http_app``.
+    """
+    uvicorn.run(
+        app.start_server(),
+        host=settings.HOST,
+        port=settings.PORT,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scaffold_ca_python/templates/entry_point/mcp/test_app.py.jinja2

@@ -0,0 +1,32 @@
+"""Tests for {{ project.python_package }}.application.app."""
+
+from __future__ import annotations
+
+import inspect
+
+from mcp.server.fastmcp import FastMCP
+from starlette.applications import Starlette
+
+from {{ project.python_package }}.application import app as app_module
+
+
+def test_mcp_instance_is_fastmcp() -> None:
+    """The module-level mcp variable must be a FastMCP instance."""
+    assert isinstance(app_module.mcp, FastMCP)
+
+
+def test_start_server_returns_starlette() -> None:
+    """start_server() must return a Starlette ASGI application."""
+    server = app_module.start_server()
+    assert isinstance(server, Starlette)
+
+
+def test_start_server_has_routes() -> None:
+    """The returned Starlette app must expose at least one mounted route."""
+    server = app_module.start_server()
+    assert len(server.routes) > 0
+
+
+def test_lifespan_is_callable() -> None:
+    """lifespan must be a callable (async context manager factory)."""
+    assert callable(app_module.lifespan)

scaffold_ca_python/templates/entry_point/mcp/test_prompts.py.jinja2

@@ -0,0 +1,40 @@
+"""Tests for {{ project.python_package }}.infrastructure.entry_points.mcp_server.prompts."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from unittest.mock import MagicMock
+
+from {{ project.python_package }}.infrastructure.entry_points.mcp_server.prompts import bind_prompts
+
+
+def _make_mock_mcp() -> tuple[MagicMock, dict[str, object]]:
+    """Return (mock_mcp, registered) where registered maps prompt name → handler."""
+    registered: dict[str, object] = {}
+    mock = MagicMock()
+    mock.prompt = lambda: (lambda fn: registered.setdefault(fn.__name__, fn) or fn)
+    return mock, registered
+
+
+def test_bind_prompts_is_callable() -> None:
+    """bind_prompts must be an async callable."""
+    fn = getattr(bind_prompts, "__wrapped__", bind_prompts)
+    assert inspect.iscoroutinefunction(fn), "bind_prompts must be async"
+
+
+def test_bind_prompts_registers_example_prompt() -> None:
+    """Calling bind_prompts registers 'example_prompt' on the mcp instance."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_prompts, "__wrapped__", bind_prompts)
+    asyncio.run(fn(mock_mcp))
+    assert "example_prompt" in registered
+
+
+def test_example_prompt_returns_expected_string() -> None:
+    """The example_prompt inner function returns a prompt containing the topic."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_prompts, "__wrapped__", bind_prompts)
+    asyncio.run(fn(mock_mcp))
+    result = asyncio.run(registered["example_prompt"]("Python"))  # type: ignore[operator]
+    assert "Python" in result

scaffold_ca_python/templates/entry_point/mcp/test_resources.py.jinja2

@@ -0,0 +1,47 @@
+"""Tests for {{ project.python_package }}.infrastructure.entry_points.mcp_server.resources."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from unittest.mock import MagicMock
+
+from {{ project.python_package }}.infrastructure.entry_points.mcp_server.resources import bind_resources
+
+
+def _make_mock_mcp() -> tuple[MagicMock, dict[str, object]]:
+    """Return (mock_mcp, registered) where registered maps resource URI → handler."""
+    registered: dict[str, object] = {}
+    mock = MagicMock()
+
+    def resource_decorator(uri: str, **_: object) -> object:
+        def wrapper(fn: object) -> object:
+            registered[uri] = fn
+            return fn
+        return wrapper
+
+    mock.resource = resource_decorator
+    return mock, registered
+
+
+def test_bind_resources_is_async_callable() -> None:
+    """bind_resources must be an async function (or wrap one via @inject)."""
+    fn = getattr(bind_resources, "__wrapped__", bind_resources)
+    assert inspect.iscoroutinefunction(fn), "bind_resources must be async"
+
+
+def test_bind_resources_registers_example_resource() -> None:
+    """Calling bind_resources registers 'file://example_resource' on the mcp instance."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_resources, "__wrapped__", bind_resources)
+    asyncio.run(fn(mock_mcp))
+    assert "file://example_resource" in registered
+
+
+def test_example_resource_returns_dict() -> None:
+    """The example_resource inner function returns a dict."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_resources, "__wrapped__", bind_resources)
+    asyncio.run(fn(mock_mcp))
+    result = asyncio.run(registered["file://example_resource"]())  # type: ignore[operator]
+    assert isinstance(result, dict)