wolfzbr 0.4.0__tar.gz

wolfzbr-0.4.0/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.spec
+
+# Ambientes virtuais
+.venv/
+venv/
+env/
+
+# Variáveis de ambiente
+.env
+.env.*
+!.env.example
+
+# Testes / lint
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Frontend
+node_modules/
+frontend/dist/
+frontend/test-results/
+frontend/playwright-report/
+src/wolfz/static/*
+!src/wolfz/static/.gitkeep
+
+# Workspace local e saídas do WolfzBR
+.wolfz/
+saida/
+*.hyper
+*.log
+
+# Dados de usuário (nunca versionar planilhas fora do corpus de testes)
+*.xlsx
+*.xls
+*.ods
+*.csv
+*.parquet
+!tests/corpus/**
+!src/wolfz/br/data/*.parquet
+# Download pela metade de scripts/baixar_corpus.py. O original baixado é
+# ignorado pelo .gitignore da própria pasta do corpus (F1.B2).
+tests/corpus/**/.original.*.tmp
+
+# Excel: arquivos temporários de lock
+~$*
+
+# Notebooks
+.ipynb_checkpoints/
+
+# IDE / SO
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Planejamento pessoal (não versionado)
+dev/

wolfzbr-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Gomide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wolfzbr-0.4.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: wolfzbr
+Version: 0.4.0
+Summary: Limpeza de planilhas brasileiras com receitas reproduzíveis e exportação para Power Query M, Python, Tableau e Power BI.
+Project-URL: Homepage, https://github.com/RafaelGomide/WolfzBR
+Project-URL: Repository, https://github.com/RafaelGomide/WolfzBR
+Project-URL: Issues, https://github.com/RafaelGomide/WolfzBR/issues
+Project-URL: Documentation, https://github.com/RafaelGomide/WolfzBR/blob/main/docs/system_design.md
+Author: Rafael Gomide
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brasil,excel,limpeza de dados,planilhas,polars,power bi,power query
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.111
+Requires-Dist: fastexcel>=0.11
+Requires-Dist: filelock>=3.13
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=16.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-calamine>=0.2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: python-ulid>=2.7
+Requires-Dist: rapidfuzz>=3.9
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: syrupy>=4.6; extra == 'dev'
+Provides-Extra: sql
+Requires-Dist: duckdb>=1.0; extra == 'sql'
+Provides-Extra: tableau
+Requires-Dist: tableauhyperapi>=0.0.19; extra == 'tableau'
+Description-Content-Type: text/markdown
+
+# WolfzBR
+
+[![CI](https://github.com/RafaelGomide/WolfzBR/actions/workflows/ci.yml/badge.svg)](https://github.com/RafaelGomide/WolfzBR/actions/workflows/ci.yml)
+
+Limpeza de planilhas brasileiras com receitas reproduzíveis. Você arrasta a planilha suja (título, cabeçalho no meio, totais, `1.234,56`, `R$`, datas `31/12/2024`), ajusta os passos na tela e exporta a tabela limpa junto com a **receita**: o mesmo passo a passo em Power Query M e em script Python, para refazer no mês seguinte.
+
+Tudo roda na sua máquina. Nenhum dado sai do seu computador.
+
+> **Status:** pré-alfa (0.4). O formato da receita ainda pode mudar até a 1.0.
+
+![Importar, ajustar a receita e exportar](https://raw.githubusercontent.com/RafaelGomide/WolfzBR/main/docs/demo.gif)
+
+## Instalação
+
+Requer Python 3.12 ou mais novo. Recomendado com [pipx](https://pipx.pypa.io/), que isola o WolfzBR num ambiente próprio:
+
+```bash
+pipx install wolfzbr
+```
+
+ou com `pip`, num ambiente virtual:
+
+```bash
+pip install wolfzbr
+```
+
+O pacote já traz a interface compilada; não precisa de Node.
+
+## Uso
+
+### Interface
+
+```bash
+wolfz ui
+```
+
+Abre o navegador com a interface. Para usar:
+
+1. Arraste o arquivo (`.xlsx`, `.xls`, `.ods` ou `.csv`). Se tiver mais de uma aba, escolha qual.
+2. Confira a estrutura detectada: título, cabeçalho, dados, totais e rodapé aparecem em cores. Se a área estiver errada, clique e arraste na grade para marcar a certa.
+3. Ajuste a receita: adicione, edite, reordene ou desative passos, vendo a tabela antes e depois de cada um. Clique no cabeçalho de uma coluna para ver o perfil dela.
+4. Exporte: CSV (pronto para o Excel em português), Excel, Parquet, Power Query M e script Python.
+
+A receita é salva automaticamente a cada edição. O endereço só funciona com a chave de acesso que o terminal mostra, nova a cada execução. Deixe o terminal aberto enquanto usa; Ctrl+C encerra.
+
+Opções: `--port` fixa a porta; `--no-browser` só mostra o endereço, sem abrir o navegador.
+
+### Linha de comando
+
+Aplicar uma receita salva ao arquivo do mês seguinte:
+
+```bash
+wolfz run vendas.wolfz.json vendas_fevereiro.xlsx -o saida/ --format xlsx
+```
+
+- Se algum passo não se aplicar ao arquivo novo (uma coluna mudou de nome, por exemplo), nada é gravado e a mensagem diz qual passo falhou e quais colunas existem.
+- Se a aba muda de nome todo mês (`Vendas 2024` → `Vendas 2025`), use `source.match.sheet_name_regex` na receita.
+
+Outros comandos:
+
+```bash
+wolfz inspect planilha.xlsx      # perfil das colunas no terminal
+wolfz schema                     # JSON Schema da receita
+wolfz --help
+```
+
+Códigos de saída do `run`: 0 ok · 1 um passo falhou · 2 receita inválida ou uso incorreto · 3 arquivo ilegível.
+
+### Em Python
+
+```python
+import wolfz
+
+df = wolfz.run("vendas.wolfz.json", "vendas_fevereiro.xlsx")  # polars.DataFrame
+```
+
+## Exportação
+
+| Formato | O que sai |
+|---|---|
+| CSV | UTF-8 com BOM; separador `,`, `;` ou tabulação; vírgula decimal opcional. Opção de neutralizar fórmulas (`=`, `+`, `-`, `@`). |
+| Excel (`.xlsx`) | Data como data, número como número; texto nunca vira fórmula. |
+| Parquet | Tipos preservados, compressão zstd. |
+| Power Query M | A receita como função M, para colar no Power BI ou no Excel. |
+| Script Python | A receita como script autônomo, que só depende do Polars. |
+
+Tableau (`.hyper`) e projeto do Power BI (`.pbip`) estão previstos para versões futuras.
+
+## Padrões brasileiros
+
+O catálogo tem 31 operações: estrutura (área, cabeçalho, linhas e colunas vazias, preencher para baixo, despivotar), colunas, texto e padrões brasileiros. Os padrões cobrem:
+
+- números (`1.234,56`, `(1,5)`, `10-` do SAP, `R$`);
+- percentual, datas e mês/ano;
+- sim/não;
+- CPF, CNPJ (inclusive o alfanumérico), CEP e UF.
+
+Cada operação tem a mesma regra no motor (Polars), no M e no script Python, com teste de equivalência.
+
+## Limites
+
+- Arquivo de até 100 MB.
+- Uma tabela por aba. Duas tabelas na mesma aba: marque a área de cada uma em projetos separados.
+- Cabeçalho em várias linhas é juntado num nome só, mas o cabeçalho mesclado na horizontal ainda não é preenchido. Isso chega na 0.6.
+
+## Documentação
+
+- Desenho técnico: [`docs/system_design.md`](docs/system_design.md)
+- Mudanças: [`CHANGELOG.md`](CHANGELOG.md)
+- Como contribuir: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Licença
+
+[MIT](LICENSE)

wolfzbr-0.4.0/README.md

@@ -0,0 +1,114 @@
+# WolfzBR
+
+[![CI](https://github.com/RafaelGomide/WolfzBR/actions/workflows/ci.yml/badge.svg)](https://github.com/RafaelGomide/WolfzBR/actions/workflows/ci.yml)
+
+Limpeza de planilhas brasileiras com receitas reproduzíveis. Você arrasta a planilha suja (título, cabeçalho no meio, totais, `1.234,56`, `R$`, datas `31/12/2024`), ajusta os passos na tela e exporta a tabela limpa junto com a **receita**: o mesmo passo a passo em Power Query M e em script Python, para refazer no mês seguinte.
+
+Tudo roda na sua máquina. Nenhum dado sai do seu computador.
+
+> **Status:** pré-alfa (0.4). O formato da receita ainda pode mudar até a 1.0.
+
+![Importar, ajustar a receita e exportar](https://raw.githubusercontent.com/RafaelGomide/WolfzBR/main/docs/demo.gif)
+
+## Instalação
+
+Requer Python 3.12 ou mais novo. Recomendado com [pipx](https://pipx.pypa.io/), que isola o WolfzBR num ambiente próprio:
+
+```bash
+pipx install wolfzbr
+```
+
+ou com `pip`, num ambiente virtual:
+
+```bash
+pip install wolfzbr
+```
+
+O pacote já traz a interface compilada; não precisa de Node.
+
+## Uso
+
+### Interface
+
+```bash
+wolfz ui
+```
+
+Abre o navegador com a interface. Para usar:
+
+1. Arraste o arquivo (`.xlsx`, `.xls`, `.ods` ou `.csv`). Se tiver mais de uma aba, escolha qual.
+2. Confira a estrutura detectada: título, cabeçalho, dados, totais e rodapé aparecem em cores. Se a área estiver errada, clique e arraste na grade para marcar a certa.
+3. Ajuste a receita: adicione, edite, reordene ou desative passos, vendo a tabela antes e depois de cada um. Clique no cabeçalho de uma coluna para ver o perfil dela.
+4. Exporte: CSV (pronto para o Excel em português), Excel, Parquet, Power Query M e script Python.
+
+A receita é salva automaticamente a cada edição. O endereço só funciona com a chave de acesso que o terminal mostra, nova a cada execução. Deixe o terminal aberto enquanto usa; Ctrl+C encerra.
+
+Opções: `--port` fixa a porta; `--no-browser` só mostra o endereço, sem abrir o navegador.
+
+### Linha de comando
+
+Aplicar uma receita salva ao arquivo do mês seguinte:
+
+```bash
+wolfz run vendas.wolfz.json vendas_fevereiro.xlsx -o saida/ --format xlsx
+```
+
+- Se algum passo não se aplicar ao arquivo novo (uma coluna mudou de nome, por exemplo), nada é gravado e a mensagem diz qual passo falhou e quais colunas existem.
+- Se a aba muda de nome todo mês (`Vendas 2024` → `Vendas 2025`), use `source.match.sheet_name_regex` na receita.
+
+Outros comandos:
+
+```bash
+wolfz inspect planilha.xlsx      # perfil das colunas no terminal
+wolfz schema                     # JSON Schema da receita
+wolfz --help
+```
+
+Códigos de saída do `run`: 0 ok · 1 um passo falhou · 2 receita inválida ou uso incorreto · 3 arquivo ilegível.
+
+### Em Python
+
+```python
+import wolfz
+
+df = wolfz.run("vendas.wolfz.json", "vendas_fevereiro.xlsx")  # polars.DataFrame
+```
+
+## Exportação
+
+| Formato | O que sai |
+|---|---|
+| CSV | UTF-8 com BOM; separador `,`, `;` ou tabulação; vírgula decimal opcional. Opção de neutralizar fórmulas (`=`, `+`, `-`, `@`). |
+| Excel (`.xlsx`) | Data como data, número como número; texto nunca vira fórmula. |
+| Parquet | Tipos preservados, compressão zstd. |
+| Power Query M | A receita como função M, para colar no Power BI ou no Excel. |
+| Script Python | A receita como script autônomo, que só depende do Polars. |
+
+Tableau (`.hyper`) e projeto do Power BI (`.pbip`) estão previstos para versões futuras.
+
+## Padrões brasileiros
+
+O catálogo tem 31 operações: estrutura (área, cabeçalho, linhas e colunas vazias, preencher para baixo, despivotar), colunas, texto e padrões brasileiros. Os padrões cobrem:
+
+- números (`1.234,56`, `(1,5)`, `10-` do SAP, `R$`);
+- percentual, datas e mês/ano;
+- sim/não;
+- CPF, CNPJ (inclusive o alfanumérico), CEP e UF.
+
+Cada operação tem a mesma regra no motor (Polars), no M e no script Python, com teste de equivalência.
+
+## Limites
+
+- Arquivo de até 100 MB.
+- Uma tabela por aba. Duas tabelas na mesma aba: marque a área de cada uma em projetos separados.
+- Cabeçalho em várias linhas é juntado num nome só, mas o cabeçalho mesclado na horizontal ainda não é preenchido. Isso chega na 0.6.
+
+## Documentação
+
+- Desenho técnico: [`docs/system_design.md`](docs/system_design.md)
+- Mudanças: [`CHANGELOG.md`](CHANGELOG.md)
+- Como contribuir: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Licença
+
+[MIT](LICENSE)

wolfzbr-0.4.0/hatch_build.py

@@ -0,0 +1,29 @@
+"""Hook de build do hatch: o wheel só sai com a interface compilada.
+
+A interface (``frontend/``) é compilada para ``src/wolfz/static/`` com
+``npm run build``. Esses arquivos ficam fora do Git, e esquecer o build
+publicaria um pacote sem interface. A instalação editável (``uv sync``) não
+passa por aqui. Para gerar um wheel sem interface de propósito:
+``WOLFZ_SEM_INTERFACE=1``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class ConfereInterface(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if version != "standard" or os.environ.get("WOLFZ_SEM_INTERFACE") == "1":
+            return
+        if not (Path(self.root) / "src" / "wolfz" / "static" / "index.html").is_file():
+            raise RuntimeError(
+                "A interface não foi compilada: rode `npm ci && npm run build` em frontend/ "
+                "antes de gerar o wheel (ou WOLFZ_SEM_INTERFACE=1 para gerar sem ela)."
+            )

wolfzbr-0.4.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wolfzbr"
+version = "0.4.0"
+description = "Limpeza de planilhas brasileiras com receitas reproduzíveis e exportação para Power Query M, Python, Tableau e Power BI."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rafael Gomide" }]
+keywords = ["limpeza de dados", "planilhas", "excel", "power bi", "power query", "polars", "brasil"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: Portuguese (Brazilian)",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    # Motor
+    "polars>=1.0",
+    "pyarrow>=16.0",
+    # Ingestão
+    "fastexcel>=0.11",
+    "python-calamine>=0.2",
+    "openpyxl>=3.1",
+    # Receita / validação
+    "pydantic>=2.7",
+    # Padrões BR
+    "rapidfuzz>=3.9",
+    # Workspace (ID de projeto e lock por projeto, §4.3 e §9 do design)
+    "python-ulid>=2.7",
+    "filelock>=3.13",
+    # API
+    "fastapi>=0.111",
+    "uvicorn[standard]>=0.30",
+    "python-multipart>=0.0.9",
+    # CLI
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+tableau = ["tableauhyperapi>=0.0.19"]
+sql = ["duckdb>=1.0"]
+dev = [
+    "pytest>=8.0",
+    "hypothesis>=6.100",
+    "syrupy>=4.6",
+    "ruff>=0.5",
+    "import-linter>=2.0",
+    "pytest-cov>=5.0",
+    # TestClient do FastAPI (testes de integração da API, F1.G8)
+    "httpx>=0.27",
+    "pre-commit>=3.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/RafaelGomide/WolfzBR"
+Repository = "https://github.com/RafaelGomide/WolfzBR"
+Issues = "https://github.com/RafaelGomide/WolfzBR/issues"
+Documentation = "https://github.com/RafaelGomide/WolfzBR/blob/main/docs/system_design.md"
+
+[project.scripts]
+wolfz = "wolfz.cli:app"
+
+[tool.hatch.build]
+# A interface compilada (npm run build em frontend/) fica fora do Git, mas
+# entra no wheel e no sdist: o usuário final não precisa de Node (F1.H14).
+artifacts = ["src/wolfz/static/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wolfz"]
+
+# hatch_build.py: recusa gerar o wheel sem a interface compilada.
+[tool.hatch.build.targets.wheel.hooks.custom]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/wolfz", "/README.md", "/LICENSE", "/hatch_build.py"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+src = ["src", "tests"]
+# Não formatar blocos de código dentro da documentação.
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+# Docstrings e comentários em português usam travessão e meia-risca de propósito.
+ignore = ["RUF002", "RUF003"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["wolfz"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.importlinter]
+root_package = "wolfz"
+
+[[tool.importlinter.contracts]]
+name = "Núcleo não importa API nem CLI (§6.3 do design)"
+type = "forbidden"
+source_modules = ["wolfz.core", "wolfz.ops", "wolfz.br", "wolfz.export"]
+forbidden_modules = ["wolfz.api", "wolfz.cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers", "--cov", "--cov-report=term-missing"]
+
+[tool.coverage.run]
+source = ["wolfz"]
+branch = true
+
+[tool.coverage.report]
+skip_empty = true
+show_missing = true

wolfzbr-0.4.0/src/wolfz/__init__.py

@@ -0,0 +1,22 @@
+"""WolfzBR: limpeza de planilhas brasileiras com receitas reproduzíveis.
+
+API pública mínima para uso em notebook e scripts::
+
+    import wolfz
+
+    receita = wolfz.load_recipe("vendas.wolfz.json")
+    df = wolfz.run(receita, "vendas_jan.csv")
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from wolfz.core.engine import StepError
+from wolfz.core.engine import run_file as run
+from wolfz.core.recipe import RecipeError, load_recipe
+
+try:
+    __version__ = version("wolfzbr")
+except PackageNotFoundError:  # rodando do código-fonte sem instalar
+    __version__ = "0.0.0+desconhecida"
+
+__all__ = ["RecipeError", "StepError", "__version__", "load_recipe", "run"]

wolfzbr-0.4.0/src/wolfz/api/__init__.py

@@ -0,0 +1 @@
+"""API FastAPI local: transporte, token de sessão e servir a SPA. Sem regra de negócio."""

wolfzbr-0.4.0/src/wolfz/api/app.py

@@ -0,0 +1,58 @@
+"""Aplicação FastAPI: rotas em ``/api``, a SPA compilada na raiz."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+import wolfz.ops  # noqa: F401  (registra o catálogo de operações)
+from wolfz import __version__
+from wolfz.api import problems, security
+from wolfz.api.projetos import Projetos
+from wolfz.api.rotas import router
+from wolfz.api.security import Settings
+
+_SEM_INTERFACE = """<!doctype html>
+<html lang="pt-BR"><head><meta charset="utf-8"><title>WolfzBR</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 40rem; margin: 4rem auto">
+<h1>WolfzBR</h1>
+<p>A API está no ar, mas a interface ainda não foi compilada neste pacote.</p>
+</body></html>
+"""
+
+
+def create_app(settings: Settings) -> FastAPI:
+    projetos = Projetos(settings.workspace, settings.port)
+
+    @asynccontextmanager
+    async def ciclo(app: FastAPI) -> AsyncIterator[None]:
+        yield
+        projetos.fechar_todos()  # libera os locks ao encerrar
+
+    app = FastAPI(
+        title="WolfzBR Local API",
+        version=__version__,
+        lifespan=ciclo,
+        docs_url="/api/docs" if settings.dev else None,
+        redoc_url=None,
+        openapi_url="/api/openapi.json" if settings.dev else None,
+    )
+    app.state.settings = settings
+    app.state.projetos = projetos
+    problems.install(app)
+    security.install(app, settings)
+    app.include_router(router(settings, projetos))
+
+    if (settings.static_dir / "index.html").is_file():
+        app.mount("/", StaticFiles(directory=settings.static_dir, html=True), name="spa")
+    else:
+
+        @app.get("/", include_in_schema=False)
+        def sem_interface() -> HTMLResponse:
+            return HTMLResponse(_SEM_INTERFACE)
+
+    return app