fastforge-cli 0.0.1__py3-none-any.whl

fastforge/template/{{cookiecutter.project_slug}}/.dockerignore

@@ -0,0 +1,15 @@
+**/__pycache__
+**/.git
+**/.gitignore
+**/.env
+**/.env.*
+**/.vscode
+**/.pytest_cache
+**/.coverage
+**/htmlcov
+**/docker-compose*
+**/Dockerfile*
+**/*.md
+**/tests
+**/.ruff_cache
+**/.pre-commit-config.yaml

fastforge/template/{{cookiecutter.project_slug}}/.env.staging

@@ -0,0 +1,86 @@
+# {{ cookiecutter.project_name }} — Staging
+APP_NAME={{ cookiecutter.project_slug }}
+APP_ENV=staging
+APP_DEBUG=true
+APP_PORT={{ cookiecutter.port }}
+APP_LOG_LEVEL=debug
+{%- if cookiecutter.logging == "structlog" %}
+
+# Logging
+LOG_FORMAT={{ cookiecutter.log_format }}
+LOG_FILE_ENABLED=false
+{%- endif %}
+{%- if cookiecutter.database == "postgres" %}
+
+# Database
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/{{ cookiecutter.package_name }}
+{%- endif %}
+{%- if cookiecutter.database == "mysql" %}
+
+# Database
+DATABASE_URL=mysql+aiomysql://root:root@mysql:3306/{{ cookiecutter.package_name }}
+{%- endif %}
+{%- if cookiecutter.database == "sqlite" %}
+
+# Database
+DATABASE_URL=sqlite+aiosqlite:///./{{ cookiecutter.package_name }}.db
+{%- endif %}
+{%- if cookiecutter.database == "mongodb" %}
+
+# Database
+MONGODB_URL=mongodb://mongodb:27017
+MONGODB_DATABASE={{ cookiecutter.package_name }}
+{%- endif %}
+{%- if cookiecutter.cache == "redis" or cookiecutter.streaming == "redis_pubsub" %}
+
+# Redis
+REDIS_URL=redis://redis:6379/0
+{%- endif %}
+{%- if cookiecutter.cache == "memcached" %}
+
+# Memcached
+MEMCACHED_HOST=memcached
+MEMCACHED_PORT=11211
+{%- endif %}
+{%- if cookiecutter.streaming == "kafka" %}
+
+# Kafka
+KAFKA_BOOTSTRAP_SERVERS=kafka:9092
+KAFKA_TOPIC={{ cookiecutter.project_slug }}-events
+KAFKA_GROUP_ID={{ cookiecutter.project_slug }}-group
+{%- endif %}
+{%- if cookiecutter.streaming == "rabbitmq" %}
+
+# RabbitMQ
+RABBITMQ_URL=amqp://guest:guest@rabbitmq:5672/
+{%- endif %}
+{%- if cookiecutter.streaming == "nats" %}
+
+# NATS
+NATS_URL=nats://nats:4222
+{%- endif %}
+{%- if cookiecutter.secrets == "vault" %}
+
+# Vault
+VAULT_URL=http://vault:8200
+VAULT_TOKEN=dev-only-token
+VAULT_MOUNT_POINT=secret
+VAULT_SECRET_PATH={{ cookiecutter.project_slug }}
+{%- endif %}
+{%- if cookiecutter.secrets == "aws_sm" %}
+
+# AWS Secrets Manager
+AWS_REGION=us-east-1
+AWS_SECRET_NAME={{ cookiecutter.project_slug }}
+{%- endif %}
+{%- if cookiecutter.secrets == "azure_kv" %}
+
+# Azure Key Vault
+AZURE_VAULT_URL=https://your-vault.vault.azure.net
+{%- endif %}
+{%- if cookiecutter.secrets == "gcp_sm" %}
+
+# GCP Secret Manager
+GCP_PROJECT_ID=your-project-id
+GCP_SECRET_NAME={{ cookiecutter.project_slug }}
+{%- endif %}

fastforge/template/{{cookiecutter.project_slug}}/.gitignore

@@ -0,0 +1,15 @@
+.env
+.env.local
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+.ruff_cache/

fastforge/template/{{cookiecutter.project_slug}}/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest tests/ -x -q
+        language: system
+        pass_filenames: false
+        always_run: true

fastforge/template/{{cookiecutter.project_slug}}/Dockerfile

@@ -0,0 +1,30 @@
+FROM python:{{cookiecutter.python_version}}-slim AS base
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+RUN pip install --no-cache-dir .
+
+COPY app/ app/
+{%- if cookiecutter.log_connector == "file" %}
+
+RUN mkdir -p /var/log/app
+{%- endif %}
+
+RUN adduser --disabled-password --gecos "" appuser \
+{%- if cookiecutter.log_connector == "file" %}
+    && chown -R appuser:appuser /var/log/app
+{%- endif %}
+
+USER appuser
+
+EXPOSE {{cookiecutter.port}}
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:{{cookiecutter.port}}/health || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "{{cookiecutter.port}}", "--log-level", "info"]

fastforge/template/{{cookiecutter.project_slug}}/README.md

@@ -0,0 +1,254 @@
+# {{ cookiecutter.project_name }}
+
+> {{ cookiecutter.description }}
+
+**Author:** {{ cookiecutter.author_name }}
+**Python:** {{ cookiecutter.python_version }}
+**Port:** {{ cookiecutter.port }}
+
+---
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run development server
+uvicorn app.main:app --reload --port {{ cookiecutter.port }}
+```
+{%- if cookiecutter.docker == "yes" %}
+
+### With Docker
+
+```bash
+# Start all services
+docker compose up --build
+
+# Logs
+docker compose logs -f app
+```
+{%- if cookiecutter.docker_debug == "yes" %}
+
+### Debug Mode (VS Code)
+
+```bash
+docker compose -f docker-compose.debug.yml up
+# Attach VS Code debugger to port 5678
+```
+{%- endif %}
+{%- endif %}
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check |
+| `GET` | `/api/v1/{{ cookiecutter.model_name_plural }}` | List {{ cookiecutter.model_name_plural }} |
+| `POST` | `/api/v1/{{ cookiecutter.model_name_plural }}` | Create {{ cookiecutter.model_name }} |
+| `GET` | `/api/v1/{{ cookiecutter.model_name_plural }}/{id}` | Get {{ cookiecutter.model_name }} |
+| `PUT` | `/api/v1/{{ cookiecutter.model_name_plural }}/{id}` | Update {{ cookiecutter.model_name }} |
+| `DELETE` | `/api/v1/{{ cookiecutter.model_name_plural }}/{id}` | Delete {{ cookiecutter.model_name }} |
+
+## Architecture (SOLID)
+
+```
+app/
+├── main.py                          # App factory, middleware
+├── config.py                        # Settings (pydantic-settings)
+├── dependencies.py                  # FastAPI DI wiring
+├── api/
+│   ├── exception_handlers.py        # Structured error responses
+│   ├── routes/
+│   │   ├── health.py                # Health + readiness
+│   │   └── {{ cookiecutter.model_name_plural }}.py             # CRUD routes
+│   └── models/
+│       └── {{ cookiecutter.model_name }}.py              # Pydantic schemas
+├── services/
+│   └── {{ cookiecutter.model_name }}_service.py          # Business logic
+├── repositories/
+│   └── {{ cookiecutter.model_name }}_repository.py       # Data access
+{%- if cookiecutter.database != "none" %}
+├── db/models/
+│   └── {{ cookiecutter.model_name }}.py                  # DB model
+{%- endif %}
+└── middleware/
+    ├── security_headers.py          # Security headers
+    └── logging_middleware.py         # Request logging
+```
+
+## Tests
+
+```bash
+pytest tests/ -v
+pytest tests/ --cov=app --cov-report=html
+```
+
+---
+
+## Features
+{%- if cookiecutter.logging == "structlog" %}
+
+### Structured Logging
+
+- **Library:** structlog
+- **Format:** {{ cookiecutter.log_format }}
+{%- if cookiecutter.log_connector != "stdout" %}
+- **Connector:** {{ cookiecutter.log_connector }}
+{%- endif %}
+- Request correlation IDs via `X-Request-ID` header
+{%- endif %}
+{%- if cookiecutter.database == "postgres" %}
+
+### Database (PostgreSQL)
+
+- **Driver:** asyncpg via SQLAlchemy async
+- Configure via `DATABASE_URL`
+{%- endif %}
+{%- if cookiecutter.database == "mysql" %}
+
+### Database (MySQL)
+
+- **Driver:** aiomysql via SQLAlchemy async
+- Configure via `DATABASE_URL`
+{%- endif %}
+{%- if cookiecutter.database == "sqlite" %}
+
+### Database (SQLite)
+
+- **Driver:** aiosqlite via SQLAlchemy async
+- Configure via `DATABASE_URL`
+{%- endif %}
+{%- if cookiecutter.database == "mongodb" %}
+
+### Database (MongoDB)
+
+- **Driver:** Motor (async)
+- Configure via `MONGODB_URL`, `MONGODB_DATABASE`
+{%- endif %}
+{%- if cookiecutter.cache == "redis" %}
+
+### Cache (Redis)
+
+- **Library:** redis-py (async)
+- Configure via `REDIS_URL`
+- Usage: `from app.cache import get_cache`
+{%- endif %}
+{%- if cookiecutter.cache == "memcached" %}
+
+### Cache (Memcached)
+
+- **Library:** aiomcache
+- Configure via `MEMCACHED_HOST`, `MEMCACHED_PORT`
+- Usage: `from app.cache import get_cache`
+{%- endif %}
+{%- if cookiecutter.cache == "in_memory" %}
+
+### Cache (In-Memory)
+
+- **Library:** cachetools (TTLCache)
+- 1024 items max, 5 min TTL
+- Usage: `from app.cache import get_cache`
+{%- endif %}
+{%- if cookiecutter.streaming == "kafka" %}
+
+### Streaming (Kafka)
+
+- **Library:** aiokafka
+- Producer: `from app.streaming.producer import send_event`
+- Consumer auto-starts in lifespan, dispatches to `app/streaming/handler.py`
+- Configure via `KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_GROUP_ID`
+{%- endif %}
+{%- if cookiecutter.streaming == "rabbitmq" %}
+
+### Streaming (RabbitMQ)
+
+- **Library:** aio-pika
+- Producer: `from app.streaming.producer import send_event`
+- Consumer auto-starts in lifespan, dispatches to `app/streaming/handler.py`
+- Configure via `RABBITMQ_URL`
+{%- endif %}
+{%- if cookiecutter.streaming == "redis_pubsub" %}
+
+### Streaming (Redis Pub/Sub)
+
+- **Library:** redis-py (async)
+- Producer: `from app.streaming.producer import send_event`
+- Consumer auto-starts in lifespan, dispatches to `app/streaming/handler.py`
+- Configure via `REDIS_URL`
+{%- endif %}
+{%- if cookiecutter.streaming == "nats" %}
+
+### Streaming (NATS)
+
+- **Library:** nats-py
+- Producer: `from app.streaming.producer import send_event`
+- Consumer auto-starts in lifespan, dispatches to `app/streaming/handler.py`
+- Configure via `NATS_URL`
+{%- endif %}
+{%- if cookiecutter.secrets == "vault" %}
+
+### Secrets (HashiCorp Vault)
+
+- **Library:** hvac
+- Secrets loaded at startup into `app.state.secrets`
+- Configure via `VAULT_URL`, `VAULT_TOKEN`
+{%- endif %}
+{%- if cookiecutter.secrets == "aws_sm" %}
+
+### Secrets (AWS Secrets Manager)
+
+- **Library:** boto3
+- Secrets loaded at startup into `app.state.secrets`
+- Configure via `AWS_REGION`, `AWS_SECRET_NAME`
+{%- endif %}
+{%- if cookiecutter.secrets == "azure_kv" %}
+
+### Secrets (Azure Key Vault)
+
+- **Library:** azure-keyvault-secrets + azure-identity
+- Secrets loaded at startup into `app.state.secrets`
+- Configure via `AZURE_VAULT_URL`
+{%- endif %}
+{%- if cookiecutter.secrets == "gcp_sm" %}
+
+### Secrets (GCP Secret Manager)
+
+- **Library:** google-cloud-secret-manager
+- Secrets loaded at startup into `app.state.secrets`
+- Configure via `GCP_PROJECT_ID`, `GCP_SECRET_NAME`
+{%- endif %}
+{%- if cookiecutter.quality_gate != "none" %}
+
+### Quality Gate
+
+- **Tool:** {{ cookiecutter.quality_gate }}
+{%- endif %}
+{%- if cookiecutter.docker == "yes" %}
+
+### Containerization
+
+- Multi-stage Dockerfile (slim base)
+- Non-root user
+- Health check built-in
+{%- endif %}
+
+## Environment
+
+Configuration is managed via environment variables. See `.env.staging`.
+
+## Extend Your Project
+
+```bash
+fastforge-infra           # Infrastructure (Kafka, ES, Vault, DB)
+fastforge-cicd            # CI/CD pipeline
+fastforge-secops          # Security tools
+fastforge-helm            # Helm chart
+fastforge-k8s             # Kubernetes manifests
+fastforge-swarm           # Docker Swarm stack
+fastforge-observability   # Tracing + Metrics
+```
+
+---
+
+*Generated with [FastForge](https://github.com/jinnabaalu/fastforge)*

fastforge/template/{{cookiecutter.project_slug}}/app/api/exception_handlers.py

@@ -0,0 +1,78 @@
+"""Structured exception handlers for consistent API error responses."""
+
+import structlog
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+logger = structlog.get_logger(__name__)
+
+
+async def http_exception_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+    """Handle HTTP exceptions with a consistent JSON structure."""
+    await logger.awarning(
+        "http_error",
+        status_code=exc.status_code,
+        detail=exc.detail,
+        path=request.url.path,
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "code": exc.status_code,
+                "message": exc.detail,
+                "path": request.url.path,
+            }
+        },
+    )
+
+
+async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    """Handle request validation errors with field-level details."""
+    await logger.awarning(
+        "validation_error",
+        path=request.url.path,
+        errors=exc.errors(),
+    )
+    return JSONResponse(
+        status_code=422,
+        content={
+            "error": {
+                "code": 422,
+                "message": "Validation error",
+                "path": request.url.path,
+                "details": [
+                    {"field": ".".join(str(loc) for loc in e["loc"]), "message": e["msg"]}
+                    for e in exc.errors()
+                ],
+            }
+        },
+    )
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Catch-all for unhandled exceptions — never leak stack traces."""
+    await logger.aexception(
+        "unhandled_error",
+        path=request.url.path,
+        exc_type=type(exc).__name__,
+    )
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": {
+                "code": 500,
+                "message": "Internal server error",
+                "path": request.url.path,
+            }
+        },
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register all exception handlers on the app."""
+    app.add_exception_handler(StarletteHTTPException, http_exception_handler)
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(Exception, unhandled_exception_handler)

fastforge/template/{{cookiecutter.project_slug}}/app/api/models/{{cookiecutter.model_name}}.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel, Field
+
+
+class {{ cookiecutter.model_name_class }}Create(BaseModel):
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = Field(None, max_length=1000)
+
+
+class {{ cookiecutter.model_name_class }}Update(BaseModel):
+    name: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = Field(None, max_length=1000)
+
+
+class {{ cookiecutter.model_name_class }}Response(BaseModel):
+    id: str
+    name: str
+    description: str | None
+
+
+class {{ cookiecutter.model_name_class }}ListResponse(BaseModel):
+    {{ cookiecutter.model_name_plural }}: list[{{ cookiecutter.model_name_class }}Response]
+    total: int

fastforge/template/{{cookiecutter.project_slug}}/app/api/routes/health.py

@@ -0,0 +1,20 @@
+from fastapi import APIRouter
+
+from app.config import settings
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+async def health_check() -> dict:
+    return {
+        "status": "healthy",
+        "service": settings.app_name,
+        "version": settings.app_version,
+        "environment": settings.app_env,
+    }
+
+
+@router.get("/ready")
+async def readiness_check() -> dict:
+    return {"status": "ready"}

fastforge/template/{{cookiecutter.project_slug}}/app/api/routes/{{cookiecutter.model_name_plural}}.py

@@ -0,0 +1,70 @@
+{% if cookiecutter.logging == "structlog" -%}
+from app.logging_config import get_logger
+{%- else -%}
+from logging import getLogger
+{%- endif %}
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.models.{{cookiecutter.model_name}} import (
+    {{cookiecutter.model_name_class}}Create,
+    {{cookiecutter.model_name_class}}ListResponse,
+    {{cookiecutter.model_name_class}}Response,
+    {{cookiecutter.model_name_class}}Update,
+)
+from app.dependencies import get_{{cookiecutter.model_name}}_service
+from app.services.{{cookiecutter.model_name}}_service import {{cookiecutter.model_name_class}}Service
+
+router = APIRouter(prefix="/api/v1/{{cookiecutter.model_name_plural}}", tags=["{{cookiecutter.model_name_plural}}"])
+{% if cookiecutter.logging == "structlog" -%}
+logger = get_logger(__name__)
+{%- else -%}
+logger = getLogger(__name__)
+{%- endif %}
+
+
+@router.post("/", response_model={{cookiecutter.model_name_class}}Response, status_code=201)
+async def create_{{cookiecutter.model_name}}(
+    data: {{cookiecutter.model_name_class}}Create,
+    service: {{cookiecutter.model_name_class}}Service = Depends(get_{{cookiecutter.model_name}}_service),
+) -> {{cookiecutter.model_name_class}}Response:
+    return await service.create(data)
+
+
+@router.get("/", response_model={{cookiecutter.model_name_class}}ListResponse)
+async def list_{{cookiecutter.model_name_plural}}(
+    service: {{cookiecutter.model_name_class}}Service = Depends(get_{{cookiecutter.model_name}}_service),
+) -> {{cookiecutter.model_name_class}}ListResponse:
+    return await service.list_all()
+
+
+@router.get("/{item_id}", response_model={{cookiecutter.model_name_class}}Response)
+async def get_{{cookiecutter.model_name}}(
+    item_id: str,
+    service: {{cookiecutter.model_name_class}}Service = Depends(get_{{cookiecutter.model_name}}_service),
+) -> {{cookiecutter.model_name_class}}Response:
+    result = await service.get_by_id(item_id)
+    if not result:
+        raise HTTPException(status_code=404, detail="{{cookiecutter.model_name_class}} not found")
+    return result
+
+
+@router.put("/{item_id}", response_model={{cookiecutter.model_name_class}}Response)
+async def update_{{cookiecutter.model_name}}(
+    item_id: str,
+    data: {{cookiecutter.model_name_class}}Update,
+    service: {{cookiecutter.model_name_class}}Service = Depends(get_{{cookiecutter.model_name}}_service),
+) -> {{cookiecutter.model_name_class}}Response:
+    result = await service.update(item_id, data)
+    if not result:
+        raise HTTPException(status_code=404, detail="{{cookiecutter.model_name_class}} not found")
+    return result
+
+
+@router.delete("/{item_id}", status_code=204)
+async def delete_{{cookiecutter.model_name}}(
+    item_id: str,
+    service: {{cookiecutter.model_name_class}}Service = Depends(get_{{cookiecutter.model_name}}_service),
+) -> None:
+    deleted = await service.delete(item_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="{{cookiecutter.model_name_class}} not found")

fastforge/template/{{cookiecutter.project_slug}}/app/cache.py

@@ -0,0 +1,63 @@
+"""Cache client — {{ cookiecutter.cache }} backend."""
+{%- if cookiecutter.cache == "redis" %}
+
+import redis.asyncio as redis
+
+from app.config import settings
+
+_client: redis.Redis | None = None
+
+
+async def get_cache() -> redis.Redis:
+    """Get the Redis cache client (lazy init)."""
+    global _client  # noqa: PLW0603
+    if _client is None:
+        _client = redis.from_url(settings.redis_url, decode_responses=True)
+    return _client
+
+
+async def close_cache() -> None:
+    """Close the Redis connection pool."""
+    global _client  # noqa: PLW0603
+    if _client is not None:
+        await _client.aclose()
+        _client = None
+{%- elif cookiecutter.cache == "memcached" %}
+
+import aiomcache
+
+from app.config import settings
+
+_client: aiomcache.Client | None = None
+
+
+def get_cache() -> aiomcache.Client:
+    """Get the Memcached client (lazy init)."""
+    global _client  # noqa: PLW0603
+    if _client is None:
+        _client = aiomcache.Client(settings.memcached_host, settings.memcached_port)
+    return _client
+
+
+async def close_cache() -> None:
+    """Close the Memcached connection."""
+    global _client  # noqa: PLW0603
+    if _client is not None:
+        await _client.close()
+        _client = None
+{%- elif cookiecutter.cache == "in_memory" %}
+
+from cachetools import TTLCache
+
+_cache: TTLCache = TTLCache(maxsize=1024, ttl=300)
+
+
+def get_cache() -> TTLCache:
+    """Get the in-memory TTL cache (1024 items, 5 min TTL)."""
+    return _cache
+
+
+async def close_cache() -> None:
+    """Clear the in-memory cache."""
+    _cache.clear()
+{%- endif %}