innovationhub-cli 1.1.0 → 2.0.1

package/templates/python/README.md

@@ -0,0 +1,219 @@
+# Template FastAPI — Innovation Hub
+
+Template base para inicialização de projetos backend com **FastAPI**. Inclui autenticação completa, gerenciamento de usuários e uma estrutura modular pronta para expandir.
+
+## ✨ Funcionalidades Incluídas
+
+- **Autenticação e Autorização**: Sistema completo de login com JWT (JSON Web Tokens), refresh tokens rotativos e controle de acesso baseado em papéis (Roles).
+- **Gerenciamento de Usuários**: CRUD de usuários com criptografia de senhas (bcrypt), soft delete, paginação e reset de senha por admin.
+- **Base Genérica Reutilizável**: `BaseModel`, `BaseRepository` com generics Python para criar novos módulos rapidamente.
+- **Documentação de API**: Geração automática de documentação interativa com **Swagger (OpenAPI)** — nativa do FastAPI.
+- **Utilitários**: Paginação, geração de slugs, constantes de erro centralizadas e query params base.
+
+## 🚀 Tecnologias Utilizadas
+
+- **Framework**: [FastAPI](https://fastapi.tiangolo.com/)
+- **Linguagem**: [Python](https://www.python.org/) (3.11+)
+- **Banco de Dados**: [PostgreSQL](https://www.postgresql.org/)
+- **ORM**: [SQLAlchemy 2.0](https://www.sqlalchemy.org/) (async)
+- **Migrations**: [Alembic](https://alembic.sqlalchemy.org/)
+- **Containerização**: [Docker](https://www.docker.com/) e Docker Compose
+- **Autenticação**: [python-jose](https://python-jose.readthedocs.io/) (JWT) + [passlib](https://passlib.readthedocs.io/) (bcrypt)
+- **Validação de Dados**: [Pydantic v2](https://docs.pydantic.dev/)
+- **Configuração**: [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+- **Testes**: [pytest](https://pytest.org/) + [httpx](https://www.python-httpx.org/)
+- **Lint/Formatação**: [ruff](https://docs.astral.sh/ruff/)
+
+---
+
+## 🏁 Como Começar
+
+### Pré-requisitos
+
+- [Python](https://www.python.org/) (3.11 ou superior)
+- [Docker](https://www.docker.com/get-started) e Docker Compose
+
+### 1. Clone o Repositório
+
+```bash
+git clone <URL_DO_REPOSITORIO>
+cd <NOME_DO_PROJETO>
+```
+
+### 2. Configure as Variáveis de Ambiente
+
+```bash
+# No Windows
+copy .env.example .env
+
+# No Linux ou macOS
+cp .env.example .env
+```
+
+Preencha as variáveis no arquivo `.env`. As credenciais padrão do Postgres já funcionam com o Docker Compose.
+
+### 3. Instale as Dependências
+
+```bash
+# Crie um ambiente virtual
+python -m venv .venv
+
+# Ative o ambiente virtual
+# Windows:
+.venv\Scripts\activate
+# Linux/macOS:
+source .venv/bin/activate
+
+# Instale o projeto
+pip install -e ".[dev]"
+```
+
+---
+
+## 🐳 Executando com Docker (Recomendado)
+
+### Subir o Ambiente de Desenvolvimento
+
+```bash
+docker-compose --profile dev up -d --build
+```
+
+### Subir o Ambiente de Produção
+
+```bash
+docker-compose --profile prod up -d --build
+```
+
+- A API estará disponível em `http://localhost:3000`.
+- O banco de dados PostgreSQL estará acessível na porta `5432`.
+
+### Parar o Ambiente
+
+```bash
+docker-compose down
+```
+
+---
+
+## ⚙️ Executando Localmente (Sem Docker)
+
+### 1. Execute um Banco de Dados PostgreSQL
+
+Garanta que uma instância do PostgreSQL esteja rodando e que as credenciais no `.env` estejam corretas.
+
+### 2. Execute as Migrations
+
+```bash
+alembic upgrade head
+```
+
+### 3. Inicie a Aplicação
+
+```bash
+uvicorn app.main:app --reload --port 3000
+```
+
+A aplicação estará disponível em `http://localhost:3000`.
+
+---
+
+## 📄 Documentação e Endpoints
+
+### Acessar a Documentação
+
+Com a aplicação em execução:
+
+- **Swagger UI**: [http://localhost:3000/api/docs](http://localhost:3000/api/docs)
+- **ReDoc**: [http://localhost:3000/api/redoc](http://localhost:3000/api/redoc)
+
+### Resumo dos Endpoints Principais
+
+- `POST /auth/login`: Autentica um usuário e retorna tokens JWT.
+- `POST /auth/logout`: Faz logout (revoga refresh token).
+- `POST /auth/refresh`: Atualiza os tokens de acesso usando um refresh token.
+- `PATCH /auth/change-password`: Altera a senha do usuário logado.
+- `GET /users/me`: Retorna o perfil do usuário autenticado.
+- `PATCH /users/me`: Atualiza o perfil do usuário autenticado.
+- `GET /users/`: Lista todos os usuários (admin).
+- `GET /users/paginated`: Lista usuários com paginação e busca (admin).
+- `GET /users/{user_id}`: Busca um usuário pelo ID (admin).
+- `POST /users/`: Cria um novo usuário (admin).
+- `PATCH /users/{user_id}`: Atualiza um usuário pelo ID (admin).
+- `PATCH /users/{user_id}/reset-password`: Reseta a senha de um usuário (admin).
+- `DELETE /users/{user_id}`: Deleta um usuário (admin).
+
+---
+
+## 📂 Estrutura do Projeto
+
+```
+app/
+├── auth/           # Autenticação: JWT, dependencies, schemas, service, router
+├── common/         # Base genérica (model, repository), utilitários, paginação, schemas
+├── core/           # Configuração (settings) e banco de dados (SQLAlchemy async)
+├── user/           # Módulo de gerenciamento de usuários (CRUD completo)
+└── main.py         # Ponto de entrada da aplicação (FastAPI bootstrap)
+
+alembic/
+├── env.py          # Configuração do Alembic
+├── script.py.mako  # Template de migration
+└── versions/       # Arquivos de migration gerados
+```
+
+---
+
+## 🔌 Addons Disponíveis
+
+Na pasta `addons/` do repositório de templates, você encontra módulos opcionais:
+
+| Addon        | Descrição                                                             |
+| ------------ | --------------------------------------------------------------------- |
+| `.github`    | Workflows de CI/CD, Dependabot, labeler, semantic PR, stale issues    |
+| `pre-commit` | `.pre-commit-config.yaml` para Conventional Commits e lint pré-commit |
+| `cloudinary` | Módulo Python para upload, delete e replace de imagens no Cloudinary  |
+
+---
+
+## 🔧 Scripts Úteis
+
+### Migrations com Alembic
+
+```bash
+# Gerar uma nova migration
+alembic revision --autogenerate -m "descricao da migration"
+
+# Executar migrations pendentes
+alembic upgrade head
+
+# Reverter a última migration
+alembic downgrade -1
+
+# Ver status das migrations
+alembic current
+```
+
+### Testes
+
+```bash
+# Executar todos os testes
+pytest
+
+# Executar com cobertura
+pytest --cov=app
+
+# Executar em modo verboso
+pytest -v
+```
+
+### Lint e Formatação
+
+```bash
+# Verificar erros com ruff
+ruff check .
+
+# Corrigir automaticamente
+ruff check --fix .
+
+# Formatar código
+ruff format .
+```

package/templates/python/addons/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 10

package/templates/python/addons/.github/labeler.yml

@@ -0,0 +1,29 @@
+# Area Labels
+area/auth:
+  - app/auth/**/*
+
+area/user:
+  - app/user/**/*
+
+area/common:
+  - app/common/**/*
+
+area/core:
+  - app/core/**/*
+
+# Type Labels (Inferred from files)
+documentation:
+  - README.md
+  - LICENSE
+  - "**/*.md"
+
+ci:
+  - .github/**/*
+
+test:
+  - tests/**/*
+  - "**/*test*.py"
+
+dependencies:
+  - pyproject.toml
+  - requirements*.txt

package/templates/python/addons/.github/workflows/check-branch.yml

@@ -0,0 +1,24 @@
+name: Check Branch Up-to-Date
+
+on:
+  pull_request:
+    branches: [main, develop, master, dev]
+
+jobs:
+  check-up-to-date:
+    name: Check if branch is up-to-date
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if branch is up-to-date
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          git fetch origin ${{ github.head_ref }}
+          if ! git merge-base --is-ancestor origin/${{ github.base_ref }} origin/${{ github.head_ref }}; then
+            echo "::error::Branch is behind ${{ github.base_ref }}. Please merge/rebase before continuing."
+            exit 1
+          fi

package/templates/python/addons/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+on:
+  push:
+    branches: [main, develop, master, dev]
+  pull_request:
+    branches: [main, develop, master, dev]
+
+jobs:
+  build-and-test:
+    name: Build and Test
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format check
+        run: ruff format --check .
+      - name: Test
+        run: pytest

package/templates/python/addons/.github/workflows/draft-release.yml

@@ -0,0 +1,22 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  update_release_draft:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/templates/python/addons/.github/workflows/pr-labeler.yml

@@ -0,0 +1,16 @@
+name: "Pull Request Labeler"
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  triage:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: "${{ secrets.GITHUB_TOKEN }}"
+          sync-labels: true

package/templates/python/addons/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e .
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          generate_release_notes: true

package/templates/python/addons/.github/workflows/security-audit.yml

@@ -0,0 +1,21 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, develop, master, dev]
+  pull_request:
+    branches: [main, develop, master, dev]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e . pip-audit
+      - name: Audit dependencies
+        run: pip-audit

package/templates/python/addons/.github/workflows/semantic-pr.yml

@@ -0,0 +1,31 @@
+name: Semantic PR
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false

package/templates/python/addons/.github/workflows/stale.yml

@@ -0,0 +1,24 @@
+name: "Stale"
+on:
+  schedule:
+    - cron: "30 1 */4 * *"
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: "Esta issue está inativa há 60 dias. Marque como 'fresco' ou comente para reativar."
+          stale-pr-message: "Este PR está inativo há 60 dias. Marque como 'fresco' ou comente para reativar."
+          close-issue-message: "Esta issue foi fechada por inatividade."
+          close-pr-message: "Este PR foi fechado por inatividade."
+          days-before-issue-stale: 60
+          days-before-pr-stale: 60
+          days-before-issue-close: 7
+          days-before-pr-close: 7
+          exempt-issue-labels: "security,bug,enhancement,pinned,long-term"
+          exempt-pr-labels: "security,bug,enhancement,pinned,long-term"

package/templates/python/addons/addons.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "cloudinary",
+    "label": "Cloudinary (Upload de Imagens)",
+    "dest": "app/cloudinary"
+  },
+  {
+    "name": ".github",
+    "label": "GitHub Actions (CI/CD)",
+    "dest": ".github"
+  },
+  {
+    "name": "pre-commit",
+    "label": "Pre-commit (Lint & Formatação)",
+    "dest": "."
+  }
+]

package/templates/python/addons/cloudinary/service.py

@@ -0,0 +1,67 @@
+"""
+Addon: Cloudinary — Serviço de upload de imagens.
+
+Para usar, adicione 'cloudinary' ao pyproject.toml:
+    dependencies = [..., "cloudinary>=1.36.0"]
+
+E copie este arquivo para app/cloudinary/service.py
+"""
+
+import cloudinary
+import cloudinary.uploader
+from fastapi import HTTPException, UploadFile, status
+
+from app.common.errors import ERRORS
+from app.core.config import settings
+
+
+def configure_cloudinary() -> None:
+    """Configura o Cloudinary. Chame no startup da aplicação."""
+    cloudinary.config(
+        cloud_name=settings.CLOUDINARY_CLOUD_NAME,
+        api_key=settings.CLOUDINARY_API_KEY,
+        api_secret=settings.CLOUDINARY_API_SECRET,
+        secure=True,
+    )
+
+
+async def upload_image(file: UploadFile, folder: str) -> dict:
+    """Faz upload de uma imagem para o Cloudinary."""
+    if not file:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=ERRORS["IMAGE"]["REQUIRED"],
+        )
+
+    contents = await file.read()
+    import base64
+
+    file_base64 = base64.b64encode(contents).decode("utf-8")
+    data_uri = f"data:{file.content_type};base64,{file_base64}"
+
+    result = cloudinary.uploader.upload(data_uri, folder=folder, resource_type="image")
+    return result
+
+
+async def delete_image(public_id: str) -> dict:
+    """Deleta uma imagem do Cloudinary pelo public_id."""
+    return cloudinary.uploader.destroy(public_id)
+
+
+async def replace_image(file: UploadFile, folder: str, old_public_id: str | None = None) -> dict:
+    """Substitui uma imagem: deleta a antiga (se existir) e faz upload da nova."""
+    if not file:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=ERRORS["IMAGE"]["REQUIRED"],
+        )
+    if old_public_id:
+        await delete_image(old_public_id)
+    return await upload_image(file, folder)
+
+
+async def delete_images(public_ids: list[str]) -> dict:
+    """Deleta múltiplas imagens do Cloudinary."""
+    if not public_ids:
+        return {}
+    return cloudinary.api.delete_resources(public_ids)

package/templates/python/addons/pre-commit/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+# Addon: pre-commit
+# Equivalente ao .husky do NestJS para projetos Python.
+# Para instalar: pip install pre-commit && pre-commit install
+
+repos:
+  # Ruff: linter e formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Conventional Commits
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.0.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args:
+          - feat
+          - fix
+          - docs
+          - style
+          - refactor
+          - perf
+          - test
+          - build
+          - ci
+          - chore
+          - revert

package/templates/python/alembic/env.py

@@ -0,0 +1,56 @@
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+from app.auth.models import RefreshToken  # noqa: F401
+from app.common.base_model import Base
+from app.core.config import settings
+
+# Importar todos os models para que o Alembic os detecte
+from app.user.models import User  # noqa: F401
+
+config = context.config
+
+# Sobrescrever URL com a do settings
+config.set_main_option("sqlalchemy.url", settings.database_url_sync)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Roda migrations em modo 'offline'."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Roda migrations em modo 'online'."""
+    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/python/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"}