feat: merge feature/develop into main (v0.1.9)

.claude/commands/documentar.md

@@ -41,6 +41,8 @@ markdown_extensions:
   - tables
   - toc:
       permalink: true
+  - attr_list
+  - md_in_html
 
 extra_javascript:
   - https://unpkg.com/mermaid@10/dist/mermaid.min.js
@@ -108,6 +110,68 @@ docs/
     └── arquitetura.md              ← diagrama Mermaid + descrição de componentes
 ```
 
+## Screenshots do frontend
+
+A documentação **deve incluir prints reais da interface**. Siga este processo:
+
+### 1. Verificar se o frontend está rodando
+
+Antes de tirar screenshots, verifique se o frontend já está acessível em `http://localhost:5173`. Use a ferramenta `browser_navigate` para navegar até a URL e `browser_take_screenshot` para capturar.
+
+Se o frontend não estiver rodando, inicie com:
+
+```bash
+docker compose up frontend -d
+```
+
+Aguarde alguns segundos e verifique novamente.
+
+### 2. Screenshots a capturar
+
+Salve todos os screenshots em `docs/assets/screenshots/`. Crie a pasta se não existir. Use os nomes de arquivo abaixo (exatos, sem espaços):
+
+| Arquivo                          | O que capturar                                                                 |
+|----------------------------------|--------------------------------------------------------------------------------|
+| `visao-geral.png`                | A interface completa com painel lateral + canvas (domínio ecommerce carregado) |
+| `modal-ia.png`                   | O modal de geração com IA aberto, com provider e prompt preenchidos            |
+| `diagrama-relacional.png`        | O canvas com um diagrama relacional com pelo menos 3 tabelas conectadas        |
+| `catalogo-faker.png`             | O painel do catálogo Faker aberto                                              |
+| `yaml-exportado.png`             | A aba de YAML exportado com código visível                                     |
+| `run-generator.png`              | O modal "Run Generator" / painel de execução aberto                            |
+
+### 3. Como tirar os screenshots
+
+Use a sequência de ferramentas MCP de browser:
+
+1. `browser_navigate` → `http://localhost:5173`
+2. `browser_take_screenshot` → salva a visão geral
+3. Para abrir modais: use `browser_click` no botão correspondente, depois `browser_take_screenshot`
+4. Para carregar um domínio: use `browser_select_option` ou `browser_click` no seletor de domínio
+
+Após cada screenshot, salve o arquivo em `docs/assets/screenshots/<nome>.png` usando a ferramenta `Write` com o conteúdo binário retornado, **ou** use `browser_take_screenshot` com o parâmetro de caminho de saída se disponível.
+
+### 4. Referenciar nas páginas
+
+Após salvar os screenshots, referencie-os nas páginas correspondentes do MkDocs:
+
+- `docs/frontend/visao-geral.md` → `![Visão geral da interface](../assets/screenshots/visao-geral.png)`
+- `docs/frontend/ia.md` → `![Modal de geração com IA](../assets/screenshots/modal-ia.png)`
+- `docs/frontend/diagrama.md` → `![Diagrama relacional](../assets/screenshots/diagrama-relacional.png)`
+- `docs/frontend/faker.md` → `![Catálogo Faker](../assets/screenshots/catalogo-faker.png)`
+- `docs/frontend/yaml.md` → `![YAML exportado](../assets/screenshots/yaml-exportado.png)`
+
+Posicione cada imagem logo após o primeiro parágrafo introdutório da página, antes do detalhamento.
+
+### 5. Se o frontend não puder ser iniciado
+
+Se após tentar subir com Docker o frontend ainda não estiver acessível, registre no chat:
+
+> "Frontend indisponível para screenshots. As páginas de interface foram documentadas sem capturas de tela. Execute `docker compose up frontend` e rode `/documentar` novamente para adicionar os prints."
+
+Não bloqueie a geração do restante da documentação por causa dos screenshots — eles são adicionais, não bloqueantes.
+
+---
+
 ## O que ler antes de escrever
 
 Leia os arquivos abaixo para entender o estado atual do projeto antes de escrever qualquer coisa:

.github/workflows/ci.yml

@@ -2,15 +2,14 @@ name: CI
 
 on:
   push:
-    branches-ignore: []   # runs on all branches including main
+    branches-ignore: ["main"]
   pull_request:
     branches: ["main"]
 
 jobs:
   lint:
     name: Lint & Format
     runs-on: ubuntu-latest
-    if: github.ref_name != 'main'
     steps:
       - uses: actions/checkout@v4
 
@@ -26,7 +25,6 @@ jobs:
     name: Tests
     runs-on: ubuntu-latest
     needs: lint
-    if: github.ref_name != 'main'
     steps:
       - uses: actions/checkout@v4
 
@@ -52,11 +50,31 @@ jobs:
           files: coverage.xml
           fail_ci_if_error: false
 
+  frontend-test:
+    name: Frontend Tests
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: src/dataforge/frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: src/dataforge/frontend
+
+      - name: Run tests
+        run: npm test
+        working-directory: src/dataforge/frontend
+
   build:
     name: Build Package
     runs-on: ubuntu-latest
-    needs: test
-    if: github.ref_name != 'main'
+    needs: [test, frontend-test]
     steps:
       - uses: actions/checkout@v4
 
@@ -76,8 +94,8 @@ jobs:
   open-pr:
     name: Open PR to main
     runs-on: ubuntu-latest
-    needs: [lint, test]
-    if: github.event_name == 'push' && github.ref_name != 'main'
+    needs: [lint, test, frontend-test]
+    if: github.event_name == 'push'
     permissions:
       pull-requests: write
       contents: read
@@ -104,68 +122,3 @@ jobs:
               --title "feat: merge ${BRANCH} into main (v${VERSION})" \
               --body-file /tmp/pr_body.md
           fi
-
-  docs:
-    name: Deploy Docs
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref_name == 'main'
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install MkDocs
-        run: pip install mkdocs mkdocs-material
-
-      - name: Deploy to GitHub Pages
-        run: mkdocs gh-deploy --force
-
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    if: github.event_name == 'push' && github.ref_name == 'main'
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Read version from pyproject.toml
-        id: version
-        run: |
-          VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
-          echo "value=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Check if tag already exists
-        id: tag_check
-        run: |
-          if git ls-remote --tags origin "refs/tags/${{ steps.version.outputs.tag }}" | grep -q .; then
-            echo "exists=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "exists=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Create git tag
-        if: steps.tag_check.outputs.exists == 'false'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag "${{ steps.version.outputs.tag }}"
-          git push origin "${{ steps.version.outputs.tag }}"
-
-      - name: Create GitHub Release
-        if: steps.tag_check.outputs.exists == 'false'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh release create "${{ steps.version.outputs.tag }}" \
-            --title "Dataforge ${{ steps.version.outputs.tag }}" \
-            --generate-notes

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    branches: ["main"]
+
+jobs:
+  docs:
+    name: Deploy Docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: pip install mkdocs mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+          echo "value=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag already exists
+        id: tag_check
+        run: |
+          if git ls-remote --tags origin "refs/tags/${{ steps.version.outputs.tag }}" | grep -q .; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create git tag
+        if: steps.tag_check.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "${{ steps.version.outputs.tag }}"
+          git push origin "${{ steps.version.outputs.tag }}"
+
+      - name: Create GitHub Release
+        if: steps.tag_check.outputs.exists == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "Dataforge ${{ steps.version.outputs.tag }}" \
+            --generate-notes

.gitignore

@@ -195,6 +195,7 @@ pyrightconfig.json
 # End of https://www.toptal.com/developers/gitignore/api/python,visualstudiocode
 # Dataforge specific
 output/
+data/
 credentials/*
 !credentials/*.example
 !credentials/*.example.json

.pre-commit-config.yaml

@@ -14,3 +14,10 @@ repos:
         language: system
         pass_filenames: false
         always_run: true
+
+      - id: frontend-test
+        name: vitest (frontend)
+        entry: bash -c 'cd src/dataforge/frontend && npm test'
+        language: system
+        pass_filenames: false
+        files: ^src/dataforge/frontend/src/.*\.(ts|tsx)$

docker-compose.yml

@@ -20,6 +20,8 @@ services:
       # Volume nomeado protege o node_modules Linux do build
       # (impede que o mount acima sobrescreva com binários Windows do host)
       - frontend_node_modules:/app/src/dataforge/frontend/node_modules
+      # Dados persistidos: usuários, env-keys, JWT secret
+      - ./data:/app/data
     environment:
       - PYTHONPATH=/app/src
     restart: unless-stopped

docs/avancado/arquitetura.md

@@ -14,10 +14,13 @@ flowchart LR
         UI --> SW
     end
 
-    subgraph Server["Servidor Vite / Backend Python"]
-        API_SCHEMAS[GET /api/schemas\nGET /api/schemas/:nome\nPUT /api/schemas/:nome\nDELETE /api/schemas/:nome]
+    subgraph Server["Servidor Vite (Node.js)"]
+        API_AUTH[POST /api/auth/register\nPOST /api/auth/login]
+        API_SCHEMAS[GET /api/schemas\nPOST /api/save-schema]
         API_AI[POST /api/ai-generate\nPOST /api/ai-models]
         API_DB[POST /api/test-db-connection]
+        API_CLI[POST /api/run-cli\nPOST /api/stop-cli\nGET /api/run-history]
+        API_SCHED[GET /api/schedules\nPOST /api/schedules]
     end
 
     subgraph Core["Core Python"]
@@ -45,9 +48,12 @@ flowchart LR
         OLLAMA[Ollama local]
     end
 
+    UI -- HTTP --> API_AUTH
     UI -- HTTP --> API_SCHEMAS
     UI -- HTTP --> API_AI
     UI -- HTTP --> API_DB
+    UI -- HTTP --> API_CLI
+    UI -- HTTP --> API_SCHED
     API_AI --> ANTHROPIC
     API_AI --> OPENAI
     API_AI --> GOOGLE
@@ -81,17 +87,27 @@ flowchart LR
 
 ### Servidor (vite.config.ts)
 
-O servidor de desenvolvimento do Vite expõe endpoints de API via proxy ou plugin. Os endpoints disponíveis são:
+O servidor de desenvolvimento do Vite expõe endpoints de API via plugin. Os endpoints disponíveis são:
 
 | Endpoint | Método | Descrição |
 |----------|--------|-----------|
+| `/api/auth/register` | POST | Registra novo usuário |
+| `/api/auth/login` | POST | Autentica usuário e retorna JWT |
+| `/api/auth/me` | GET | Retorna dados do usuário autenticado |
 | `/api/schemas` | GET | Lista schemas disponíveis |
-| `/api/schemas/:nome` | GET | Retorna o YAML de um schema |
-| `/api/schemas/:nome` | PUT | Salva um schema no servidor |
-| `/api/schemas/:nome` | DELETE | Remove um schema do servidor |
+| `/api/save-schema` | POST | Salva schema no servidor |
 | `/api/ai-generate` | POST | Gera schema via IA |
 | `/api/ai-models` | POST | Lista modelos disponíveis para o provider |
 | `/api/test-db-connection` | POST | Testa uma connection string SQL |
+| `/api/run-cli` | POST | Executa o CLI com os parâmetros fornecidos |
+| `/api/stop-cli` | POST | Para a execução do CLI em andamento |
+| `/api/run-history` | GET | Lista o histórico de execuções |
+| `/api/schedules` | GET | Lista execuções agendadas |
+| `/api/schedules` | POST | Cria uma nova execução agendada |
+| `/api/credential-profiles` | GET/POST | Gerencia perfis de credenciais cloud |
+| `/api/profile/env-keys` | GET/POST/DELETE | Gerencia chaves de API salvas por usuário |
+| `/api/capabilities` | GET | Retorna capacidades disponíveis no servidor |
+| `/api/browse-folder` | GET | Navega pelo sistema de arquivos do servidor |
 
 ### Core Python
 

docs/cli/referencia.md

@@ -35,9 +35,11 @@ Gera datasets e opcionalmente escreve em arquivos, faz upload para nuvem ou carr
 | `--db-url` | | — | string | Connection string SQLAlchemy para carga SQL |
 | `--if-exists` | | `replace` | choice | O que fazer se a tabela SQL já existir: `replace`, `append` ou `fail` |
 | `--db-schema` | | — | string | Schema do banco de destino |
+| `--partition-date-granularity` | | — | string | Trunca valores de data nas partições: `granularidade` ou `tabela:granularidade`. Opções: `year` (→ YYYY) ou `month` (→ YYYY-MM) (repetível) |
 | `--recurrence` | `-R` | — | float | Intervalo em segundos entre batches (modo contínuo) |
 | `--count` | | `0` | int | Número de batches no modo recorrente (`0` = infinito) |
 | `--increment` | | — | string | Desloca valores de coluna a cada batch: `tabela:coluna:passo[:unidade]` (repetível) |
+| `--workers` | | `16` | int | Máximo de threads paralelas para escrita particionada |
 
 ### Unidades para `--increment`
 

docs/frontend/diagrama.md

@@ -2,6 +2,8 @@
 
 O canvas central da interface exibe as tabelas do schema como nós interativos conectados por setas que representam as chaves estrangeiras.
 
+![Diagrama relacional](../assets/screenshots/diagrama-relacional.png)
+
 ## Tecnologia
 
 O diagrama é construído com **ReactFlow**. Cada tabela é um nó do tipo `tableNode` (componente customizado) e cada FK é uma aresta animada.