@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/stacks/python-fastapi/alembic/env.py

@@ -0,0 +1,46 @@
+"""Alembic env — reads DATABASE_URL from settings, uses our Base metadata."""
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.core.config import settings
+from app.db.session import Base
+from app.models import User  # noqa: F401  ensure metadata is populated
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/templates/stacks/python-fastapi/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

package/templates/stacks/python-fastapi/alembic/versions/0001_create_users.py.j2

@@ -0,0 +1,37 @@
+"""create users table
+
+Revision ID: 0001_create_users
+Revises:
+Create Date: 2026-06-01 00:00:00
+"""
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "0001_create_users"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "users",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("email", sa.String(length=254), nullable=False),
+        sa.Column("password", sa.String(length=255), nullable=False),
+        sa.Column("role", sa.String(length=16), nullable=False, server_default="USER"),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False
+        ),
+        sa.UniqueConstraint("email", name="uq_users_email"),
+    )
+    op.create_index("ix_users_email", "users", ["email"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_users_email", "users")
+    op.drop_table("users")

package/templates/stacks/python-fastapi/alembic.ini.j2

@@ -0,0 +1,39 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url =
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

package/templates/stacks/python-fastapi/app/core/config.py

@@ -0,0 +1,24 @@
+"""App settings — Pydantic Settings reads from .env / environment."""
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    app_port: int = 8000
+    log_level: str = "info"
+
+    database_url: str = "postgresql+psycopg://user:pass@localhost:5432/dbname"
+
+    jwt_secret: str = "replace-me-in-prod"
+    jwt_algorithm: str = "HS256"
+    jwt_expires_min: int = 15
+
+    bcrypt_rounds: int = 12
+
+    rate_limit_per_min: int = 60
+
+    cors_origins: list[str] = ["http://localhost:3000"]
+
+
+settings = Settings()

package/templates/stacks/python-fastapi/app/core/security.py

@@ -0,0 +1,34 @@
+"""JWT + password hashing helpers."""
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from app.core.config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto", bcrypt__rounds=settings.bcrypt_rounds)
+
+
+def hash_password(plain: str) -> str:
+    return pwd_context.hash(plain)
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+
+def create_access_token(sub: str, claims: dict[str, Any] | None = None) -> tuple[str, int]:
+    expires = datetime.now(timezone.utc) + timedelta(minutes=settings.jwt_expires_min)
+    payload: dict[str, Any] = {"sub": sub, "exp": expires}
+    if claims:
+        payload.update(claims)
+    token = jwt.encode(payload, settings.jwt_secret, algorithm=settings.jwt_algorithm)
+    return token, settings.jwt_expires_min * 60
+
+
+def decode_access_token(token: str) -> dict[str, Any] | None:
+    try:
+        return jwt.decode(token, settings.jwt_secret, algorithms=[settings.jwt_algorithm])
+    except JWTError:
+        return None

package/templates/stacks/python-fastapi/app/db/session.py

@@ -0,0 +1,22 @@
+"""SQLAlchemy engine + session + declarative Base."""
+from collections.abc import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from app.core.config import settings
+
+engine = create_engine(settings.database_url, pool_pre_ping=True)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+class Base(DeclarativeBase):
+    """Declarative base for all ORM models."""
+
+
+def get_db() -> Generator[Session, None, None]:
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

package/templates/stacks/python-fastapi/app/main.py.j2

@@ -0,0 +1,36 @@
+"""FastAPI app entrypoint."""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
+
+from app.core.config import settings
+from app.routers import auth, users
+
+limiter = Limiter(key_func=get_remote_address, default_limits=[f"{settings.rate_limit_per_min}/minute"])
+
+app = FastAPI(
+    title="{{ projectName }}",
+    version="0.1.0",
+    description="DARE-shaped FastAPI API",
+)
+
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(auth.router, prefix="/auth", tags=["auth"])
+app.include_router(users.router, prefix="/users", tags=["users"])
+
+
+@app.get("/healthz", include_in_schema=False)
+def healthz() -> dict[str, str]:
+    return {"status": "ok"}

package/templates/stacks/python-fastapi/app/models/__init__.py

@@ -0,0 +1,3 @@
+from app.models.user import User
+
+__all__ = ["User"]

package/templates/stacks/python-fastapi/app/models/user.py

@@ -0,0 +1,30 @@
+"""User ORM model."""
+import uuid
+from datetime import datetime
+from enum import Enum
+
+from sqlalchemy import DateTime, Index, String, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.session import Base
+
+
+class Role(str, Enum):
+    USER = "USER"
+    ADMIN = "ADMIN"
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email: Mapped[str] = mapped_column(String(254), unique=True, nullable=False)
+    password: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[str] = mapped_column(String(16), nullable=False, default=Role.USER.value)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    __table_args__ = (Index("ix_users_email", "email"),)

package/templates/stacks/python-fastapi/app/repositories/user_repository.py

@@ -0,0 +1,34 @@
+"""User repository — encapsulates SQLAlchemy queries."""
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.user import User
+
+
+class UserRepository:
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    def find_by_email(self, email: str) -> User | None:
+        return self.db.execute(select(User).where(User.email == email)).scalar_one_or_none()
+
+    def page(self, page: int, limit: int) -> tuple[list[User], int]:
+        page = max(1, page)
+        limit = min(100, max(1, limit))
+        offset = (page - 1) * limit
+        items = list(
+            self.db.execute(
+                select(User).order_by(User.created_at.desc()).offset(offset).limit(limit)
+            )
+            .scalars()
+            .all()
+        )
+        total = self.db.execute(select(func.count()).select_from(User)).scalar_one()
+        return items, total
+
+    def create(self, *, email: str, password: str, role: str) -> User:
+        user = User(email=email, password=password, role=role)
+        self.db.add(user)
+        self.db.commit()
+        self.db.refresh(user)
+        return user

package/templates/stacks/python-fastapi/app/routers/auth.py

@@ -0,0 +1,37 @@
+"""Auth router: POST /auth/login, GET /auth/me."""
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy.orm import Session
+
+from app.core.security import decode_access_token
+from app.db.session import get_db
+from app.repositories.user_repository import UserRepository
+from app.schemas.user import LoginIn, LoginOut, UserOut
+from app.services.auth_service import AuthService, InvalidCredentials
+
+router = APIRouter()
+bearer = HTTPBearer(auto_error=True)
+
+
+@router.post("/login", response_model=LoginOut)
+def login(dto: LoginIn, db: Session = Depends(get_db)) -> LoginOut:
+    service = AuthService(UserRepository(db))
+    try:
+        return service.login(dto)
+    except InvalidCredentials as exc:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid credentials") from exc
+
+
+@router.get("/me", response_model=UserOut)
+def me(
+    creds: HTTPAuthorizationCredentials = Depends(bearer),
+    db: Session = Depends(get_db),
+) -> UserOut:
+    payload = decode_access_token(creds.credentials)
+    if not payload or "sub" not in payload:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token")
+    repo = UserRepository(db)
+    user = repo.find_by_email(payload.get("email", ""))
+    if user is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "User not found")
+    return UserOut.model_validate(user)

package/templates/stacks/python-fastapi/app/routers/users.py

@@ -0,0 +1,46 @@
+"""Users router: GET /users, POST /users."""
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy.orm import Session
+
+from app.core.security import decode_access_token
+from app.db.session import get_db
+from app.repositories.user_repository import UserRepository
+from app.schemas.user import UserCreate, UserOut, UserPage
+from app.services.user_service import EmailAlreadyInUse, UserService
+
+router = APIRouter()
+bearer = HTTPBearer(auto_error=True)
+
+
+def _require_admin(creds: HTTPAuthorizationCredentials) -> None:
+    payload = decode_access_token(creds.credentials)
+    if not payload or payload.get("role") != "ADMIN":
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "admin role required")
+
+
+@router.get("", response_model=UserPage)
+def list_users(
+    page: int = Query(1, ge=1),
+    limit: int = Query(20, ge=1, le=100),
+    creds: HTTPAuthorizationCredentials = Depends(bearer),
+    db: Session = Depends(get_db),
+) -> UserPage:
+    payload = decode_access_token(creds.credentials)
+    if not payload:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid token")
+    return UserService(UserRepository(db)).list(page, limit)
+
+
+@router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+def create_user(
+    dto: UserCreate,
+    creds: HTTPAuthorizationCredentials = Depends(bearer),
+    db: Session = Depends(get_db),
+) -> UserOut:
+    _require_admin(creds)
+    service = UserService(UserRepository(db))
+    try:
+        return service.create(dto)
+    except EmailAlreadyInUse as exc:
+        raise HTTPException(status.HTTP_409_CONFLICT, "email already in use") from exc

package/templates/stacks/python-fastapi/app/schemas/user.py

@@ -0,0 +1,56 @@
+"""Pydantic IN/OUT schemas for user resource."""
+import re
+import uuid
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+
+class LoginIn(BaseModel):
+    email: EmailStr
+    password: Annotated[str, Field(min_length=8)]
+
+    @field_validator("password")
+    @classmethod
+    def password_complexity(cls, v: str) -> str:
+        if not re.search(r"[A-Z]", v):
+            raise ValueError("password must contain an uppercase letter")
+        if not re.search(r"\d", v):
+            raise ValueError("password must contain a digit")
+        return v
+
+
+class LoginOut(BaseModel):
+    access_token: str
+    expires_in: int
+    token_type: Literal["bearer"] = "bearer"
+
+
+class UserOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: uuid.UUID
+    email: EmailStr
+    role: str
+    created_at: datetime
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: Annotated[str, Field(min_length=8)]
+    role: Literal["USER", "ADMIN"] = "USER"
+
+    @field_validator("password")
+    @classmethod
+    def password_complexity(cls, v: str) -> str:
+        if not re.search(r"[A-Z]", v):
+            raise ValueError("password must contain an uppercase letter")
+        if not re.search(r"\d", v):
+            raise ValueError("password must contain a digit")
+        return v
+
+
+class UserPage(BaseModel):
+    items: list[UserOut]
+    total: int
+    page: int

package/templates/stacks/python-fastapi/app/services/auth_service.py

@@ -0,0 +1,22 @@
+"""Authentication service — login flow."""
+from app.core.security import create_access_token, verify_password
+from app.repositories.user_repository import UserRepository
+from app.schemas.user import LoginIn, LoginOut
+
+
+class InvalidCredentials(Exception):
+    """Raised when email or password don't match."""
+
+
+class AuthService:
+    def __init__(self, repo: UserRepository) -> None:
+        self.repo = repo
+
+    def login(self, dto: LoginIn) -> LoginOut:
+        user = self.repo.find_by_email(dto.email.lower().strip())
+        if user is None or not verify_password(dto.password, user.password):
+            raise InvalidCredentials
+        token, expires_in = create_access_token(
+            str(user.id), claims={"email": user.email, "role": user.role}
+        )
+        return LoginOut(access_token=token, expires_in=expires_in)

package/templates/stacks/python-fastapi/app/services/user_service.py

@@ -0,0 +1,31 @@
+"""User service — create/list business logic."""
+from app.core.security import hash_password
+from app.repositories.user_repository import UserRepository
+from app.schemas.user import UserCreate, UserOut, UserPage
+
+
+class EmailAlreadyInUse(Exception):
+    """Raised when a user with the same email already exists."""
+
+
+class UserService:
+    def __init__(self, repo: UserRepository) -> None:
+        self.repo = repo
+
+    def list(self, page: int, limit: int) -> UserPage:
+        items, total = self.repo.page(page, limit)
+        return UserPage(
+            items=[UserOut.model_validate(u) for u in items],
+            total=total,
+            page=max(1, page),
+        )
+
+    def create(self, dto: UserCreate) -> UserOut:
+        if self.repo.find_by_email(dto.email.lower().strip()) is not None:
+            raise EmailAlreadyInUse
+        created = self.repo.create(
+            email=dto.email.lower().strip(),
+            password=hash_password(dto.password),
+            role=dto.role,
+        )
+        return UserOut.model_validate(created)

package/templates/stacks/python-fastapi/gitignore

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

package/templates/stacks/python-fastapi/llms.txt.j2

@@ -0,0 +1,53 @@
+# {{ projectName }}
+
+DARE-shaped FastAPI 0.115+ API. Layered Design: Router → Service → Repository → Model.
+
+## Setup
+
+```bash
+cp .env.example .env
+docker compose up -d postgres
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+alembic upgrade head
+uvicorn app.main:app --reload
+```
+
+## Commands
+
+- `uvicorn app.main:app --reload` — dev server (port 8000)
+- `pytest` — pytest suite
+- `ruff check .` — lint
+- `pip-audit` — dependency audit
+- `alembic revision --autogenerate -m "..."` — new migration
+- `alembic upgrade head` — apply migrations
+
+## Endpoints
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| POST | `/auth/login` | none | Exchange email+password for JWT |
+| GET | `/auth/me` | Bearer | Current user info |
+| GET | `/users` | Bearer | List users (query: page, limit) |
+| POST | `/users` | Bearer (admin) | Create user |
+| GET | `/openapi.json` | none | OpenAPI 3.1 document |
+| GET | `/docs` | none | Swagger UI |
+
+## Layered Design
+
+- `app/routers/` — HTTP layer (FastAPI APIRouter)
+- `app/services/` — business logic
+- `app/repositories/` — DB queries via SQLAlchemy
+- `app/models/` — SQLAlchemy declarative
+- `app/schemas/` — Pydantic IN/OUT
+
+Routers never touch SQLAlchemy directly — they call services which call repositories.
+
+## Env vars
+
+See `.env.example`. Required: `DATABASE_URL`, `JWT_SECRET`.
+
+## DARE skills
+
+See `.dare/skills.yml`.

package/templates/stacks/python-fastapi/openapi.json.j2

@@ -0,0 +1,43 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "{{ projectName }}",
+    "version": "0.1.0",
+    "description": "DARE-shaped FastAPI API"
+  },
+  "paths": {
+    "/auth/login": {
+      "post": {
+        "summary": "Exchange email+password for JWT",
+        "responses": {
+          "200": { "description": "JWT issued" },
+          "401": { "description": "Invalid credentials" }
+        }
+      }
+    },
+    "/auth/me": {
+      "get": {
+        "summary": "Current user",
+        "security": [{ "bearer": [] }],
+        "responses": { "200": { "description": "User" }, "401": { "description": "Unauthorized" } }
+      }
+    },
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "security": [{ "bearer": [] }],
+        "responses": { "200": { "description": "Page of users" } }
+      },
+      "post": {
+        "summary": "Create user (admin)",
+        "security": [{ "bearer": [] }],
+        "responses": { "201": { "description": "Created" }, "403": { "description": "Forbidden" } }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
+    }
+  }
+}