workspai 0.43.0

package/templates/kits/fastapi-ddd/src/app/main.py.j2

@@ -0,0 +1,61 @@
+"""Application factory wiring the FastAPI instance for DDD layers."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from src.routing import api_router as root_api_router
+
+try:
+    # canonical health package
+    from src.health import register_health_routes as _core_register_health_routes
+except ImportError:  # pragma: no cover - health package not generated yet
+
+    def _register_health_routes(_: FastAPI) -> None:
+        return None
+
+else:
+
+    def _register_health_routes(app: FastAPI) -> None:
+        try:
+            _core_register_health_routes(app)
+        except Exception:  # pragma: no cover - defensive best-effort registration
+            return None
+
+
+LifespanHandler = Callable[[FastAPI], AsyncIterator[None]]
+
+
+def create_app(
+    *,
+    title: str,
+    description: str,
+    version: str,
+    lifespan: LifespanHandler | None = None,
+) -> FastAPI:
+    """Build the FastAPI application configured with shared middlewares and routers."""
+
+    app = FastAPI(
+        title=title,
+        description=description,
+        version=version,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(root_api_router, prefix="/api")
+    _register_health_routes(app)
+
+    return app

package/templates/kits/fastapi-ddd/src/app/presentation/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Presentation layer packages (HTTP, CLI, messaging, ...)."""
+
+__all__ = ["api"]

package/templates/kits/fastapi-ddd/src/app/presentation/api/__init__.py.j2

@@ -0,0 +1,5 @@
+"""HTTP-facing presentation layer."""
+
+from .router import get_api_router
+
+__all__ = ["get_api_router"]

package/templates/kits/fastapi-ddd/src/app/presentation/api/dependencies/__init__.py.j2

@@ -0,0 +1,19 @@
+"""FastAPI dependencies that wire infrastructure to application use-cases."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from src.app.application.interfaces import ServiceContext
+from src.app.infrastructure.repositories import InMemoryNoteRepository, StaticHealthRepository
+
+
+@lru_cache(maxsize=1)
+def get_service_context() -> ServiceContext:
+    """Return a cached service context for request handlers."""
+    health_repository = StaticHealthRepository()
+    note_repository = InMemoryNoteRepository()
+    return ServiceContext(health_provider=health_repository, note_repository=note_repository)
+
+
+__all__ = ["get_service_context"]

package/templates/kits/fastapi-ddd/src/app/presentation/api/router.py.j2

@@ -0,0 +1,10 @@
+"""Factory for the root API router."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+
+def get_api_router() -> APIRouter:
+    """Return an API router ready for versioned sub-routers."""
+    return APIRouter()

package/templates/kits/fastapi-ddd/src/app/presentation/api/routes/__init__.py.j2

@@ -0,0 +1,5 @@
+"""HTTP routes exposed by the presentation layer."""
+
+from . import health, notes
+
+__all__ = ["health", "notes"]

package/templates/kits/fastapi-ddd/src/app/presentation/api/routes/health.py.j2

@@ -0,0 +1,27 @@
+"""Health endpoints bridging the DDD layers."""
+
+from __future__ import annotations
+
+from time import monotonic
+
+from fastapi import APIRouter, Depends
+
+from src.app.application.interfaces import ServiceContext
+from src.app.application.use_cases import get_service_health
+from src.app.presentation.api.dependencies import get_service_context
+
+router = APIRouter(tags=["health"])
+
+_START_TIME = monotonic()
+
+
+@router.get("/", summary="Health check")
+async def heartbeat(
+    context: ServiceContext = Depends(get_service_context),
+) -> dict[str, object]:
+    """Return the current service health decal."""
+    payload: dict[str, object] = dict(get_service_health(context))
+    payload.setdefault("version", "{{ app_version }}")
+    payload.setdefault("uptime", monotonic() - _START_TIME)
+    payload.setdefault("module", "service")
+    return payload

package/templates/kits/fastapi-ddd/src/app/presentation/api/routes/notes.py.j2

@@ -0,0 +1,50 @@
+"""HTTP handlers for the example notes feature."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from src.app.application.interfaces import ServiceContext
+from src.app.application.use_cases import create_note, get_note, list_notes
+from src.app.domain.models import NoteDraft
+from src.app.presentation.api.dependencies import get_service_context
+
+router = APIRouter(tags=["examples"])
+
+
+class NotePayload(BaseModel):
+    title: str = Field(..., max_length=80)
+    body: str = Field(..., max_length=500)
+
+
+class NoteResponse(NotePayload):
+    id: int
+
+
+@router.post("/notes", response_model=NoteResponse, status_code=status.HTTP_201_CREATED)
+async def create_example_note(
+    payload: NotePayload,
+    context: ServiceContext = Depends(get_service_context),
+) -> NoteResponse:
+    note = create_note(context, NoteDraft(title=payload.title, body=payload.body))
+    return NoteResponse(**note.to_dict())
+
+
+@router.get("/notes", response_model=list[NoteResponse])
+async def list_example_notes(
+    context: ServiceContext = Depends(get_service_context),
+) -> list[NoteResponse]:
+    notes = list_notes(context)
+    return [NoteResponse(**note.to_dict()) for note in notes]
+
+
+@router.get("/notes/{note_id}", response_model=NoteResponse)
+async def get_example_note(
+    note_id: int,
+    context: ServiceContext = Depends(get_service_context),
+) -> NoteResponse:
+    note = get_note(context, note_id)
+    if not note:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Note not found")
+    return NoteResponse(**note.to_dict())

package/templates/kits/fastapi-ddd/src/app/shared/__init__.py.j2

@@ -0,0 +1,5 @@
+"""Shared utilities across layers."""
+
+from .result import Result
+
+__all__ = ["Result"]

package/templates/kits/fastapi-ddd/src/app/shared/result.py.j2

@@ -0,0 +1,28 @@
+"""Basic result type shared across layers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Optional, TypeVar
+
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+@dataclass(frozen=True, slots=True)
+class Result(Generic[T, E]):
+    """Simple functional-style result wrapper."""
+
+    value: Optional[T] = None
+    error: Optional[E] = None
+
+    @property
+    def is_ok(self) -> bool:
+        return self.error is None
+
+    @property
+    def is_err(self) -> bool:
+        return self.error is not None
+
+
+__all__ = ["Result"]

package/templates/kits/fastapi-ddd/src/cli.py.j2

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Project CLI wrapper for {{ project_name }} (DDD edition).
+
+Prefer a per-project CLI in `.workspai/cli.py` when present. Otherwise
+provide helpful guidance to the developer rather than guessing environment
+details.
+"""
+
+import importlib.util
+import sys
+import argparse
+from pathlib import Path
+from typing import Optional
+
+
+def _missing_cli(name: str) -> None:
+    print(f"❌ Missing project-local CLI (.workspai/cli.py) - can't run '{name}'")
+    print("💡 If you're a new user run: workspai init  # create venv + install deps")
+    sys.exit(127)
+
+
+def _load_project_cli_module() -> Optional[object]:
+    project_root = Path(__file__).resolve().parents[1]
+    cli_file = project_root / ".workspai" / "cli.py"
+    if not cli_file.exists():
+        legacy_cli_file = project_root / ".rapidkit" / "cli.py"
+        if not legacy_cli_file.exists():
+            return None
+        cli_file = legacy_cli_file
+    spec = importlib.util.spec_from_file_location("project_cli", str(cli_file))
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)  # type: ignore
+    return module
+
+
+_mod = _load_project_cli_module()
+
+
+# Default placeholders -- call `_missing_cli` if the project-local CLI isn't
+# available. These are real functions so linters don't complain.
+def init() -> None:
+    _missing_cli("init")
+
+
+def dev() -> None:
+    _missing_cli("dev")
+
+
+def start() -> None:
+    _missing_cli("start")
+
+
+def build() -> None:
+    _missing_cli("build")
+
+
+def test() -> None:
+    _missing_cli("test")
+
+
+def lint() -> None:
+    _missing_cli("lint")
+
+
+def format() -> None:  # type: ignore[misc]
+    _missing_cli("format")
+
+
+def help_cmd() -> None:
+    print("Usage: poetry run <command>  # (init|dev|start|build|test|lint|format)")
+
+
+if _mod is not None:
+    # prefer project-provided implementations when available
+    init = getattr(_mod, "init", init)
+    dev = getattr(_mod, "dev", dev)
+    start = getattr(_mod, "start", start)
+    build = getattr(_mod, "build", build)
+    test = getattr(_mod, "test", test)
+    lint = getattr(_mod, "lint", lint)
+    format = getattr(_mod, "format", format)
+    help_cmd = getattr(_mod, "help_cmd", help_cmd)
+
+
+_dev_impl = dev
+_start_impl = start
+
+
+def _runtime_kwargs_from_argv(argv: list[str]) -> dict:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("-p", "--port", type=int, dest="port")
+    parser.add_argument("--host", dest="host")
+    parser.add_argument("--allow-global-runtime", action="store_true", dest="allow_global_runtime")
+    ns, _ = parser.parse_known_args(argv)
+
+    kwargs = {}
+    if ns.port is not None:
+        kwargs["port"] = ns.port
+    if ns.host is not None:
+        kwargs["host"] = ns.host
+    if ns.allow_global_runtime:
+        kwargs["allow_global_runtime"] = True
+    return kwargs
+
+
+def dev() -> None:  # type: ignore[no-redef]
+    kwargs = _runtime_kwargs_from_argv(sys.argv[1:])
+    try:
+        _dev_impl(**kwargs)
+    except TypeError:
+        _dev_impl()
+
+
+def start() -> None:  # type: ignore[no-redef]
+    kwargs = _runtime_kwargs_from_argv(sys.argv[1:])
+    try:
+        _start_impl(**kwargs)
+    except TypeError:
+        _start_impl()
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        help_cmd()
+        return
+
+    command = sys.argv[1]
+    commands = {
+        "init": init,
+        "dev": dev,
+        "start": start,
+        "build": build,
+        "test": test,
+        "lint": lint,
+        "format": format,
+        "help": help_cmd,
+    }
+
+    if command in commands:
+        if command in ("dev", "start"):
+            parser = argparse.ArgumentParser(prog=f"poetry run {command}", add_help=False)
+            parser.add_argument("-p", "--port", type=int, dest="port")
+            parser.add_argument("--host", dest="host")
+            parser.add_argument("--allow-global-runtime", action="store_true", dest="allow_global_runtime")
+            ns, _ = parser.parse_known_args(sys.argv[2:])
+
+            kwargs = {}
+            if ns.port is not None:
+                kwargs["port"] = ns.port
+            if ns.host is not None:
+                kwargs["host"] = ns.host
+            if ns.allow_global_runtime:
+                kwargs["allow_global_runtime"] = True
+
+            try:
+                commands[command](**kwargs)
+            except TypeError:
+                commands[command]()
+        else:
+            commands[command]()
+    else:
+        print(f"Unknown command: {command}")
+        print("Run 'poetry run help' to see available commands.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/kits/fastapi-ddd/src/main.py.j2

@@ -0,0 +1,35 @@
+"""{{ project_name }} FastAPI application entrypoint (DDD)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from src.app.main import create_app
+
+# <<<inject:imports>>>
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Coordinate startup/shutdown hooks contributed by RapidKit Core modules."""
+
+    _ = app  # ensure the app reference stays available for injected hooks
+    # <<<inject:startup>>>
+    try:
+        yield
+    finally:
+        # <<<inject:shutdown>>>
+        pass
+
+
+app: FastAPI = create_app(
+    title="{{ project_name }}",
+    description="{{ description }}",
+    version="{{ app_version }}",
+    lifespan=lifespan,
+)
+
+# <<<inject:routes>>>

package/templates/kits/fastapi-ddd/src/modules/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Module bootstrap namespace."""
+
+# <<<inject:module-init>>>

package/templates/kits/fastapi-ddd/src/routing/__init__.py.j2

@@ -0,0 +1,13 @@
+"""API router assembly bridging DDD presentation routes."""
+
+from __future__ import annotations
+
+from src.app.presentation.api.router import get_api_router
+from .health import router as health_router
+from .notes import router as notes_router
+# <<<inject:router-imports>>>
+
+api_router = get_api_router()
+api_router.include_router(health_router, prefix="/health", tags=["health"])
+api_router.include_router(notes_router, prefix="/examples", tags=["examples"])
+# <<<inject:router-mount>>>

package/templates/kits/fastapi-ddd/src/routing/health.py.j2

@@ -0,0 +1,7 @@
+"""Health endpoints re-export for module compatibility."""
+
+from __future__ import annotations
+
+from src.app.presentation.api.routes.health import router
+
+__all__ = ["router"]

package/templates/kits/fastapi-ddd/src/routing/notes.py.j2

@@ -0,0 +1,7 @@
+"""Re-export example note routes for compatibility with module injection."""
+
+from __future__ import annotations
+
+from src.app.presentation.api.routes.notes import router
+
+__all__ = ["router"]

package/templates/kits/fastapi-ddd/tests/__init__.py.j2

@@ -0,0 +1 @@
+"""Test package placeholder."""

package/templates/kits/fastapi-ddd/tests/test_app_factory.py.j2

@@ -0,0 +1,22 @@
+"""Smoke tests for the generated FastAPI DDD scaffold."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from src.app.main import create_app
+from src.main import app
+
+
+def test_create_app_returns_fastapi_instance() -> None:
+    instance = create_app(title="Test", description="Sample", version="1.0.0")
+    assert isinstance(instance, FastAPI)
+    assert instance.title == "Test"
+
+
+def test_health_route_returns_ok() -> None:
+    client = TestClient(app)
+    response = client.get("/api/health/")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"

package/templates/kits/fastapi-ddd/tests/test_health.py.j2

@@ -0,0 +1,17 @@
+"""Health-check regression tests for FastAPI DDD projects."""
+
+from fastapi.testclient import TestClient
+
+from src.main import app
+
+client = TestClient(app)
+
+
+def test_health_endpoint() -> None:
+    response = client.get("/api/health/")
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["status"] == "ok"
+    assert "version" in payload
+    assert "uptime" in payload
+    assert "module" in payload

package/templates/kits/fastapi-ddd/tests/test_notes.py.j2

@@ -0,0 +1,27 @@
+"""Example feature tests exercising the DDD notes handlers."""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from src.main import app
+
+client = TestClient(app)
+
+
+def test_create_and_fetch_note() -> None:
+    payload = {"title": "architecture note", "body": "Documented via FastAPI DDD kit."}
+    create_response = client.post("/api/examples/notes", json=payload)
+    assert create_response.status_code == 201
+    body = create_response.json()
+    note_id = body["id"]
+    assert body["title"] == payload["title"]
+
+    get_response = client.get(f"/api/examples/notes/{note_id}")
+    assert get_response.status_code == 200
+    assert get_response.json()["id"] == note_id
+
+
+def test_missing_note_returns_404() -> None:
+    response = client.get("/api/examples/notes/999")
+    assert response.status_code == 404