fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/templates/without_rbac/compose.yaml

@@ -0,0 +1,33 @@
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: project_name
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d project_name"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  api:
+    build: .
+    env_file: .env
+    environment:
+      PG_HOST: db
+      PG_SSLMODE: disable
+    command: ["sh", "-c", "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload"]
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+
+volumes:
+  postgres-data:
+

fastapi_forge/templates/without_rbac/pyproject.toml

@@ -0,0 +1,14 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E9", "F63", "F7", "F82"]
+
+[tool.ruff.lint.per-file-ignores]
+"app/db/models/*.py" = ["F821"]

fastapi_forge/templates/without_rbac/requirements-dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+pytest>=8.0,<9.0
+pytest-asyncio>=0.23,<1.0
+ruff>=0.8,<1.0
+

fastapi_forge/templates/without_rbac/requirements.txt

@@ -0,0 +1,16 @@
+alembic>=1.13.0
+fastapi>=0.111.0
+asyncpg>=0.30.0
+psycopg[binary]>=3.2.0
+pydantic-settings>=2.0.0
+pydantic[email]>=2.0.0
+uvicorn[standard]>=0.29.0
+SQLAlchemy>=2.0.30
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+bcrypt==4.0.1
+python-multipart>=0.0.9
+slowapi>=0.1.9
+redis>=5.0.0
+fastapi-mail>=1.4.1
+structlog>=24.0.0

fastapi_forge/templates/without_rbac/sample.env

@@ -0,0 +1,42 @@
+APP_NAME=__PROJECT_NAME__
+APP_VERSION=1.0.0
+APP_ENV=development
+APP_DEBUG=false
+SECRET_KEY=replace-with-a-long-random-secret
+
+PG_HOST=localhost
+PG_PORT=5432
+PG_DATABASE=project_name
+PG_USER=postgres
+PG_PASSWORD=postgres
+PG_SSLMODE=prefer
+
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_DAYS=7
+PASSWORD_RESET_TOKEN_EXPIRE_MINUTES=15
+ALGORITHM=HS256
+
+ALLOWED_ORIGINS=http://localhost:3000
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+USE_REDIS=false
+REDIS_URL=
+RATE_LIMIT_PER_MINUTE=60
+LOG_DIR=logs
+LOG_TO_FILES=false
+
+# Database pool tuning
+DATABASE_POOL_SIZE=10
+DATABASE_MAX_OVERFLOW=20
+DATABASE_POOL_TIMEOUT=30
+DATABASE_DEBUG=false
+
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_FROM=noreply@example.com
+MAIL_PORT=587
+MAIL_SERVER=smtp.example.com
+MAIL_STARTTLS=true
+MAIL_SSL_TLS=false
+MAIL_FROM_NAME=__PROJECT_NAME__
+FRONTEND_URL=http://localhost:3000

fastapi_forge/templates/without_rbac/scripts/seed_first_user.py

@@ -0,0 +1,51 @@
+import argparse
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from sqlalchemy import select
+
+from app.core.security import hash_password
+from app.db.models import User
+from app.db.session import SyncSessionLocal
+
+
+def username_from_email(email: str) -> str:
+    return email.split("@", 1)[0].replace(".", "_").replace("-", "_").lower()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Create the first superuser.")
+    parser.add_argument("--email", required=True)
+    parser.add_argument("--password", required=True)
+    parser.add_argument("--full-name", required=True)
+    args = parser.parse_args()
+
+    with SyncSessionLocal() as session:
+        user = session.scalar(
+            select(User).where(User.email == args.email.lower())
+        )
+        if user is None:
+            user = User(
+                email=args.email.lower(),
+                username=username_from_email(args.email),
+                full_name=args.full_name,
+                hashed_password=hash_password(args.password),
+            )
+            session.add(user)
+        user.full_name = args.full_name
+        user.hashed_password = hash_password(args.password)
+        user.is_active = True
+        user.is_superuser = True
+        user.is_verified = True
+        user.restore()
+        session.commit()
+        print(f"SUPERUSER ready: {user.email}")
+
+
+if __name__ == "__main__":
+    main()
+

fastapi_forge/templates/without_rbac/tests/test_audit.py

@@ -0,0 +1,42 @@
+from uuid import uuid4
+
+import pytest
+
+from app.db.models.audit_log import AuditLog
+from app.services.audit import AuditService
+
+
+class FakeSession:
+    def __init__(self):
+        self.added = []
+        self.flushed = False
+
+    def add(self, value):
+        self.added.append(value)
+
+    async def flush(self):
+        self.flushed = True
+
+
+@pytest.mark.asyncio
+async def test_audit_service_persists_context():
+    session = FakeSession()
+    user_id = uuid4()
+
+    entry = await AuditService(session).log(
+        action="users.update",
+        resource="users",
+        resource_id="target-user",
+        user_id=user_id,
+        old_values={"is_active": True},
+        new_values={"is_active": False},
+        metadata={"reason": "offboarding"},
+        request_id="request-123",
+    )
+
+    assert isinstance(entry, AuditLog)
+    assert entry.user_id == user_id
+    assert entry.log_metadata == {"reason": "offboarding"}
+    assert entry.request_id == "request-123"
+    assert session.added == [entry]
+    assert session.flushed

fastapi_forge/templates/without_rbac/tests/test_config.py

@@ -0,0 +1,27 @@
+import pytest
+from pydantic import ValidationError
+
+from app.core.config import Settings
+
+
+def test_database_urls_escape_credentials_and_enable_tls():
+    configured = Settings(pg_password="p@ss", pg_sslmode="require")
+
+    assert "%40" in configured.postgres_url
+    assert "ssl=require" in configured.postgres_async_url
+
+
+def test_production_rejects_unsafe_defaults():
+    with pytest.raises(ValidationError):
+        Settings(APP_ENV="production", _env_file=None)
+
+
+def test_production_accepts_explicit_secure_settings():
+    Settings(
+        APP_ENV="production",
+        SECRET_KEY="x" * 48,
+        ALLOWED_HOSTS=["api.example.com"],
+        ALLOWED_ORIGINS=["https://example.com"],
+        pg_sslmode="verify-full",
+        _env_file=None,
+    )

fastapi_forge/templates/without_rbac/tests/test_generator.py

@@ -0,0 +1,20 @@
+import ast
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_generated_non_rbac_project_structure():
+    assert not (PROJECT_ROOT / "app/api/v1/roles").exists()
+    assert not (PROJECT_ROOT / "app/api/v1/permissions").exists()
+    assert not (PROJECT_ROOT / "app/db/models/permission.py").exists()
+    assert (PROJECT_ROOT / "Dockerfile").exists()
+    assert (PROJECT_ROOT / ".github/workflows/ci.yml").exists()
+
+
+def test_python_sources_compile():
+    for path in PROJECT_ROOT.rglob("*.py"):
+        source = path.read_text(encoding="utf-8")
+        ast.parse(source, filename=str(path))
+        compile(source, str(path), "exec")

fastapi_forge/templates/without_rbac/tests/test_security.py

@@ -0,0 +1,68 @@
+from app.core.security import (
+    create_access_token,
+    create_refresh_token,
+    decode_token,
+    hash_password,
+    hash_opaque_token,
+    verify_password,
+)
+from app.api.v1.auth.schema import TokenResponse, UserResponse
+
+
+def test_password_hash_round_trip():
+    password = "StrongPassword123!"
+    hashed = hash_password(password)
+
+    assert hashed != password
+    assert verify_password(password, hashed)
+    assert not verify_password("wrong-password", hashed)
+
+
+def test_access_token_round_trip():
+    token, _ = create_access_token(
+        "user-123",
+        {"permissions": ["users:read"], "role": "ADMIN"},
+    )
+
+    payload = decode_token(token, expected_type="access")
+
+    assert payload["sub"] == "user-123"
+    assert payload["permissions"] == ["users:read"]
+    assert payload["role"] == "ADMIN"
+    assert payload["jti"]
+
+
+def test_refresh_token_round_trip():
+    token, _ = create_refresh_token("user-123")
+
+    payload = decode_token(token, expected_type="refresh")
+
+    assert payload["sub"] == "user-123"
+    assert payload["type"] == "refresh"
+
+
+def test_opaque_token_hash_is_deterministic_and_one_way():
+    token = "secret-reset-token"
+
+    assert hash_opaque_token(token) == hash_opaque_token(token)
+    assert hash_opaque_token(token) != token
+
+
+def test_refresh_token_is_excluded_from_serialized_login_response():
+    user = UserResponse(
+        id="user-123",
+        email="user@example.com",
+        username="user",
+        full_name="Example User",
+        is_active=True,
+        is_superuser=False,
+        is_verified=True,
+    )
+    response = TokenResponse(
+        access_token="access",
+        refresh_token="refresh-secret",
+        expires_in=1800,
+        user=user,
+    )
+
+    assert "refresh_token" not in response.model_dump()

fastapi_forge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: fastapi-forge-cli
+Version: 0.1.0
+Summary: Generate production-oriented FastAPI projects with optional RBAC.
+Author: FastAPI Forge Contributors
+License-Expression: MIT
+Keywords: fastapi,boilerplate,generator,rbac,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build<2.0,>=1.2; extra == "dev"
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.8; extra == "dev"
+Requires-Dist: twine<7.0,>=5.1; extra == "dev"
+Dynamic: license-file
+
+# FastAPI Forge
+
+FastAPI Forge is a zero-runtime-dependency CLI that generates production-oriented FastAPI projects with PostgreSQL, Alembic migrations, JWT authentication, audit logging, and optional role-based access control (RBAC).
+
+## Generated features
+
+- Access and rotating refresh tokens, revocation, and session management
+- Password reset and email verification flows
+- PostgreSQL with sync and async SQLAlchemy sessions
+- Alembic migrations and an idempotent first-user seed command
+- Structured logs, request IDs, rate limiting, CORS, trusted hosts, and security headers
+- Liveness, readiness, and database health endpoints
+- A multi-stage, non-root Docker image and local Compose stack
+- Pytest tests, Ruff checks, and GitHub Actions CI
+
+The RBAC variant adds hierarchical roles, permissions, per-user permissions, protected administration APIs, and RBAC seed data. The non-RBAC variant uses `is_superuser` for administrative authorization.
+
+## Requirements
+
+- Python 3.9+ for the generator
+- Python 3.12+ and PostgreSQL 14+ for generated applications
+- Docker with Compose v2 for the optional container workflow
+
+## Install
+
+Install the CLI in an isolated environment from a published package:
+
+```bash
+pipx install fastapi-forge-cli
+```
+
+Or install it into the current Python environment:
+
+```bash
+python -m pip install fastapi-forge-cli
+```
+
+The PyPI distribution is named `fastapi-forge-cli` because `fastapi-forge` is
+already used by another project. The installed terminal command remains
+`fastapi-forge`, and the Python import remains `fastapi_forge`.
+
+For development from a source checkout:
+
+```bash
+cd fastapi-forge
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .
+```
+
+For generator development, run `pip install -e ".[dev]"`. On Windows PowerShell, activate with `.venv\\Scripts\\Activate.ps1`.
+
+## Generate a project
+
+```bash
+# With RBAC
+fastapi-forge create "Inventory API" --with-rbac
+
+# Without RBAC
+fastapi-forge create "Inventory API" --without-rbac
+
+# Select a parent directory
+fastapi-forge create "Inventory API" --with-rbac --output-dir ./projects
+```
+
+The same generator is available as a Python library:
+
+```python
+from pathlib import Path
+
+from fastapi_forge import create_project
+
+project = create_project(
+    name="Inventory API",
+    output_dir=Path("./projects"),
+    with_rbac=True,
+)
+print(project)
+```
+
+Generation is staged before installation at the destination. Existing projects are
+preserved unless `--force` is explicitly supplied, and symbolic-link destinations
+are never replaced.
+
+If neither RBAC option is supplied, an interactive terminal asks which variant to use. Non-interactive environments default to RBAC. Existing destinations are protected; `--force` permanently replaces the matching generated-project directory.
+
+```text
+usage: fastapi-forge create [-h] [--output-dir OUTPUT_DIR]
+                            [--with-rbac | --without-rbac] [--force]
+                            name
+```
+
+## Getting help
+
+Discover available commands:
+
+```bash
+fastapi-forge --help
+```
+
+See every project-generation option:
+
+```bash
+fastapi-forge create --help
+```
+
+Print copy-ready examples:
+
+```bash
+fastapi-forge examples
+```
+
+Common commands include:
+
+```bash
+fastapi-forge create "Inventory API" --with-rbac
+fastapi-forge create "Public API" --without-rbac
+fastapi-forge create "Billing API" --with-rbac --output-dir ./projects
+```
+
+## Run a generated project
+
+### Python
+
+Create the PostgreSQL database described by `sample.env`, then:
+
+```bash
+cd inventory-api
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements-dev.txt
+cp sample.env .env
+alembic upgrade head
+python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+uvicorn app.main:app --reload
+```
+
+Open `http://localhost:8000/docs`. Run `pytest` and `ruff check .` before committing.
+
+### Docker
+
+```bash
+cd inventory-api
+cp sample.env .env
+docker compose up --build
+```
+
+In another terminal:
+
+```bash
+docker compose exec api python scripts/seed_first_user.py \
+  --email admin@example.com \
+  --password 'ChangeMe123!' \
+  --full-name 'System Administrator'
+```
+
+The Compose file is for local development; it uses development credentials and a bind mount.
+
+## Production deployment checklist
+
+1. Set `APP_ENV=production`.
+2. Supply a unique `SECRET_KEY` of at least 32 characters from a secret manager.
+3. Set explicit `ALLOWED_HOSTS` and HTTPS `ALLOWED_ORIGINS` values.
+4. Use managed PostgreSQL credentials and `PG_SSLMODE=require`, `verify-ca`, or `verify-full`.
+5. Configure Redis when rate limits must be shared across replicas.
+6. Configure SMTP and `FRONTEND_URL` for account emails.
+7. Run `alembic upgrade head` as one release job before starting new replicas.
+8. Terminate TLS at a trusted load balancer or reverse proxy.
+9. Send stdout/stderr to centralized logging. Enable file logs only with persistent storage.
+10. Monitor `/api/v1/health/live` and `/api/v1/health/ready`.
+11. Back up PostgreSQL, test restores, rotate secrets, and define rollback procedures.
+
+Production mode refuses startup with a default/short secret, wildcard hosts or origins, or a non-TLS database mode. Interactive API documentation is disabled.
+
+```bash
+docker build -t inventory-api:1.0.0 .
+docker run --rm --env-file .env inventory-api:1.0.0 alembic upgrade head
+docker run --rm --env-file .env -p 8000:8000 inventory-api:1.0.0
+```
+
+Do not run migrations independently from every application replica.
+
+## Generator development and release
+
+```bash
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+Review generated output from both variants whenever templates change.
+
+## License
+
+MIT