rapidkit 0.40.1 → 0.41.1

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,167 @@
+#!/usr/bin/env python3
+"""Project CLI wrapper for {{ project_name }} (DDD edition).
+
+Prefer a per-project CLI in `.rapidkit/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 (.rapidkit/cli.py) - can't run '{name}'")
+    print("💡 If you're a new user run: rapidkit 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 / ".rapidkit" / "cli.py"
+    if not cli_file.exists():
+        return None
+    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 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

package/templates/kits/fastapi-standard/README.md.j2

@@ -0,0 +1,145 @@
+# {{ project_name | replace('_', ' ') | title }}
+
+A minimal FastAPI service generated with the **FastAPI Standard Kit**. All domain-specific capabilities (configuration, logging, persistence, observability, authentication, etc.) are provided by RapidKit modules.
+
+## Quick start
+
+```bash
+# Load the project-aware RapidKit CLI (adds .rapidkit/rapidkit to PATH)
+source .rapidkit/activate
+
+# Bootstrap dependencies (creates .venv + installs Poetry-managed deps)
+rapidkit init  # use make init if you prefer a Make target
+
+# Copy env templates and install hooks/tooling
+./bootstrap.sh
+
+# Run linting, typing, testing, and supply-chain audits
+make lint
+make typecheck
+make test
+make audit
+
+# Start development server with hot reload
+make dev
+rapidkit dev  # same as make dev but auto-detects the project
+
+# Prefer RapidKit CLI helpers when you want it to resolve scripts automatically
+rapidkit lint
+rapidkit test
+rapidkit start
+```
+
+> Always run `source .rapidkit/activate` after opening a new shell so the project-local `rapidkit` launcher and helper scripts stay on your PATH.
+
+> Re-run `rapidkit init` (or `make init`) whenever dependencies change, or use `SKIP_INIT=1 make install` if you only need to refresh tooling/hooks without reinstalling packages.
+
+> Lockfiles are generated automatically during scaffolding. Set `RAPIDKIT_SKIP_LOCKS=1` (or `RAPIDKIT_GENERATE_LOCKS=0`) before running `rapidkit create` if you need to opt out.
+
+> Want the full RapidKit CLI catalog? Run `rapidkit --help` or visit the CLI reference in the docs to explore every global/project command.
+
+---
+
+## Local development
+
+- `rapidkit init` bootstraps dependencies via the project-local CLI (run it after sourcing `.rapidkit/activate`).
+- `make init` is an optional alias for `rapidkit init` when you prefer Make targets.
+- `make install` re-runs `rapidkit init` (unless you set `SKIP_INIT=1`) and refreshes developer tooling such as pre-commit hooks.
+- `./bootstrap.sh` copies `.env.example` to `.env` (if missing) and runs `SKIP_INIT=1 make install` for you.
+- `make dev` (or `rapidkit dev`) launches Uvicorn with the correct module path and reload settings.
+- `make lint`, `make typecheck`, and `make test` wrap Ruff, mypy, and pytest for consistent CI parity.
+- `make audit` shells out to `pip-audit` to surface vulnerable dependencies.
+- Prefer `rapidkit lint`, `rapidkit test`, and `rapidkit start` if you want RapidKit to autodetect the virtualenv and command wiring.
+```
+
+## Available commands
+
+```bash
+rapidkit init       # 🔧 Bootstrap the project (create .venv + install deps)
+make init           # 🔧 Optional alias for rapidkit init (wraps the local CLI)
+./bootstrap.sh      # 🪄 Copy env template + install hooks/tooling (idempotent)
+rapidkit dev        # 🚀 Start development server with hot reload
+make dev            # 🚀 Alternative via Makefile helper
+rapidkit start      # ⚡ Start production server
+rapidkit lint       # 🔧 Run lint checks via project-aware CLI
+rapidkit test       # 🧪 Run pytest through RapidKit CLI
+make install        # 📦 Install Poetry deps + hooks
+make lint           # ✅ Lint via Ruff + Black
+make typecheck      # 🔍 Run mypy on src
+make test           # 🧪 Run tests
+make audit          # 🔐 Run pip-audit across dependencies
+make docker-up      # 🐳 Start docker compose stack (if enabled)
+```
+
+## Project layout
+
+- `src/main.py` – FastAPI application entrypoint
+- `src/routing/` – Core routers (health) and anchors for module routers
+- `src/modules/` – Module bootstrap anchors
+- `pyproject.toml` – Poetry configuration and dependencies
+- `Makefile` – Common developer workflows (format, lint, docker, etc.)
+- `Dockerfile` / `docker-compose.yml` – Optional container setup for local dev and deployment
+- `.github/workflows/ci.yml` – Optional GitHub Actions pipeline for linting and tests
+
+## Example feature
+
+The scaffold ships with a tiny in-memory **notes** API mounted under `/api/examples/notes`. Use it as a safe playground for wiring routers, schemas, and tests without touching your real domain logic:
+
+```bash
+# Create a note
+curl -s -X POST http://localhost:8000/api/examples/notes \
+	-H "Content-Type: application/json" \
+	-d '{"title":"first","body":"scaffolded by RapidKit"}'
+
+# List notes
+curl -s http://localhost:8000/api/examples/notes | jq
+```
+
+The implementation intentionally stays in memory so you can replace it with a repository-backed service once you install RapidKit database modules.
+
+{% if selected_modules %}
+## Recommended RapidKit modules
+
+The following RapidKit modules are suggested during scaffolding; install them any time with `rapidkit add module <name>`:
+
+{% for module in selected_modules %}- {{ module.name | replace('_', ' ') | title }} (`{{ module.name }}`{% if not module.required %}, optional{% endif %}) – tier: {{ module.tier }}
+{% endfor %}
+{% endif %}
+
+## Adding features
+
+Use `rapidkit add module <module-name>` to install optional capabilities. Modules inject imports, routes, and services through the anchors defined in `src/main.py` and `src/routing/__init__.py`.
+
+During kit generation you can decide whether the core RapidKit modules ship with the scaffold:
+
+```text
+Install the RapidKit settings module? [Y/n]
+Install the RapidKit logging module? [Y/n]
+Install deployment module assets (Docker/CI)? [Y/n]
+```
+
+### Scaffold toggles vs RapidKit modules
+
+- `enable_*` prompts (for Docker, CI, SQLite, etc.) control the starter assets generated by this kit.
+- `install_*` prompts control which RapidKit modules are installed up front.
+- You can always add modules later with `rapidkit add module <name>` if you skip them during scaffolding.
+
+When you need deployment artefacts in an existing project, install the optional `deployment` module:
+
+```bash
+rapidkit add module deployment
+rapidkit modules lock --overwrite
+```
+
+<!-- <<<inject:module-snippet>>> -->
+
+## 📄 License
+
+This project is licensed under the **{{ license }}** License - see the `LICENSE` file included at the project root for details.
+
+## 🔒 Security & secrets
+
+- Copy `.env.example` to `.env` and populate secrets (`SECRET_KEY`, DB credentials, etc.) before deploying.
+- **Do not** commit real secrets or `.env` to git; `.gitignore` already contains `.env` to protect accidental commits.
+- For production, tighten CORS and allowed hosts rather than using wildcard settings provided for convenience in dev.
+- Run `make audit` (pip-audit) before releases to catch dependency CVEs early.

package/templates/kits/fastapi-standard/common/env.example.j2

@@ -0,0 +1,10 @@
+# RapidKit environment defaults
+PROJECT_NAME="{{ project_name | default('rapidkit-app') }}"
+ENV="development"
+DEBUG="true"
+APP_HOST="0.0.0.0"
+APP_PORT="8000"
+LOG_LEVEL="info"
+
+# Module-specific environment variables
+# <<<inject:module-env>>>

package/templates/kits/fastapi-standard/env.example.j2

@@ -0,0 +1 @@
+{% include 'common/env.example.j2' %}

package/templates/kits/fastapi-standard/pyproject.toml.j2

@@ -0,0 +1,64 @@
+[tool.poetry]
+name = "{{ project_name }}"
+version = "{{ app_version }}"
+description = "{{ description }}"
+authors = ["{{ author }} <you@example.com>"]
+license = "{{ license }}"
+packages = [{ include = "src" }]
+
+[tool.poetry.scripts]
+dev = "src.cli:dev"
+start = "src.cli:start"
+build = "src.cli:build"
+test = "src.cli:test"
+lint = "src.cli:lint"
+format = "src.cli:format"
+help = "src.cli:help_cmd"
+
+[tool.poetry.dependencies]
+python = "^{{ python_version }}"
+fastapi = "^0.128.0"
+uvicorn = { extras = ["standard"], version = "^0.40.0" }
+pydantic = "^2.12.5"
+{% if has_settings -%}
+pydantic-settings = { version = "^2.12.0", extras = ["yaml"] }
+{% endif %}
+# <<<inject:poetry-dependencies>>>
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.2"
+pytest-asyncio = "^1.3.0"
+pytest-cov = "^7.0.0"
+httpx = "^0.28.1"
+ruff = "^0.14.10"
+black = "^25.12.0"
+isort = "^7.0.0"
+mypy = "^1.19.1"
+build = "^1.3.0"
+
+# <<<inject:poetry-dev-dependencies>>>
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+markers = [
+	"integration: mark tests as integration tests",
+	"template_integration: mark template integration tests",
+]
+
+[tool.ruff]
+line-length = 100
+exclude = [".rapidkit/vendor"]
+
+[tool.ruff.lint]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "{{ python_version }}"
+ignore_missing_imports = true
+warn_unused_configs = false
+show_error_codes = true
+# Ignore vendor snapshots and generated health shims from strict static checking
+exclude = "(^\\.rapidkit/vendor/|src/health/|src/main.py$)"

package/templates/kits/fastapi-standard/src/__init__.py.j2

@@ -0,0 +1,3 @@
+"""{{ project_name }} package."""
+
+__all__ = ["main"]