chore: adiciona .gitignore e commit.command

2026-08-18 08:25:29 -04:00
parent 68958fde00
commit 8fca456ceb
215 changed files with 65752 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 01 — Arquitetura do Sistema (G-ART / fcp-mcp-server)
+
+> Referência canônica de como o sistema está dividido e implementado. Leia este
+> documento antes de qualquer mudança de código.
+
+## 1. Visão de cima (camadas)
+
+O sistema é um **servidor MCP em Python** que lê/analisa/reescreve arquivos
+**FCPXML** do Final Cut Pro. Há **três camadas** bem separadas:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  admin/  — Aplicações complementares (fora do MCP)          │
+│    models_api.py    API (FastAPI) p/ gerenciar modelos      │
+│    models_gui.py    UI desktop (Flet) p/ gerenciar modelos  │
+│    graphify.sh/.md  Pipeline de graphify do código          │
+├─────────────────────────────────────────────────────────────┤
+│  server.py  — CAMADA MCP / TRANSPORTE (NÃO tem lógica)      │
+│    62 tools, handlers, prompts, resources, dispatch         │
+│    Só valida entrada/saída e traduz JSON-RPC → chamadas     │
+├─────────────────────────────────────────────────────────────┤
+│  fcpxml/  — "ENGINE" = NÚCLEO PURO Python (desacoplado)     │
+│    Não conhece MCP nem argumentos de tool.                  │
+│    Trabalha com objetos Python e XML.                       │
+│    É o foco / onde quase tudo mora.                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Regra de arquitetura:** `server.py` NUNCA implementa lógica de timeline —
+ele delega ao `fcpxml/`. Tudo em `fcpxml/` é testável isoladamente (1032 testes).
+
+## 2. Regras transversais (convenções em todo o código)
+
+| Conceito | Regra |
+|----------|-------|
+| **Tempo** | `TimeValue` fração racional `"600/2400s"`. Nunca use float p/ tempo. |
+| **I/O paths** | Sempre via helpers `_validate_filepath` / `_validate_output_path` (sandbox). |
+| **Nome de saída** | Nunca sobrescrever original: `output_<suffix>.fcpxml`. |
+| **Segurança XML** | Sempre `defusedxml` (via `safe_xml.py`). Nunca `xml.etree` direto. |
+| **Deps opcionais** | `librosa`/`ffmpeg`/`huggingface_hub` importados **lazy**, degradam com `None`. |
+| **Lint** | `ruff check . --exclude docs/` — zero erros. |
+| **Validação pós-correção** | `./Engine/run_after_fix.sh` SEMPRE após cada correção. |
+
+## 3. Fluxo de um request (round-trip)
+
+```
+Cliente MCP (Claude)
+      │  JSON-RPC (stdio)
+      ▼
+server.py ── dispatcher (TOOL_HANDLERS)
+      │  valida path, parseia projeto, chama engine
+      ▼
+fcpxml/parser.py      XML → objetos
+fcpxml/writer.py      edita / grava
+fcpxml/rough_cut.py   gera novas timelines
+fcpxml/export.py      cross-NLE
+      ▼
+output_<suffix>.fcpxml   (original intocado)
+      ▼
+Final Cut Pro: File → Import → XML   (ou push_to_fcp, sem cliques)
+```
+
+## 4. Dual-mode: XML + Live
+
+O sistema opera em **dois modos complementares**:
+
+- **Modo XML (principal):** exporta FCPXML, processa como dados, reimporta.
+  Roda fora do FCP. Nenhuma API privada.
+- **Modo Live (`fcpxml/live.py`):** *push* do FCPXML direto p/ o FCP em
+  execução via Apple events oficiais (`Open Document`), com `import-options`.
+  Leitura de bibliotecas via AppleScript read-only.
+
+**Assimetria estrutural:** import é scriptable, mas a Apple não oferece export
+programático — round-trips voltam pelas ferramentas XML.
+
+## 5. Onde está cada responsabilidade
+
+| Responsabilidade | Fica em |
+|------------------|---------|
+| Modelos de dados (tempo, clips, markers) | `fcpxml/models.py` |
+| Parse FCPXML → objetos | `fcpxml/parser.py` |
+| Editing/escrita (modifier + writer) | `fcpxml/writer.py` |
+| Geração de timeline nova | `fcpxml/rough_cut.py` |
+| Comparação de timelines | `fcpxml/diff.py` |
+| Export cross-NLE (Resolve, FCP7) | `fcpxml/export.py` |
+| Inteligência de mídia (silêncio/beats) | `fcpxml/media_intel.py` |
+| Transcrição Whisper local | `fcpxml/transcribe.py` |
+| Gestão de modelos Whisper | `fcpxml/model_manager.py` |
+| Templates de timeline | `fcpxml/templates.py` |
+| Controle Live do FCP | `fcpxml/live.py` |
+| Segurança XML (`defusedxml`, `serialize_xml`) | `fcpxml/safe_xml.py` |
+| Validação contra DTDs da Apple | `fcpxml/dtd.py` |
+| Transporte MCP (62 tools) | `server.py` |
+
+## 6. Mapa de dependências (você está aqui se for mexer no X → quem tocar)
+
+```
+server.py ──► fcpxml/parser, writer, rough_cut, export, diff,
+               media_intel, transcribe, templates, live, dtd
+admin/models_gui.py ──► fcpxml/media_intel, model_manager,
+                        parser, transcribe
+admin/models_api.py  ──► fcpxml/model_manager
+fcpxml/writer.py     ──► fcpxml/models, safe_xml, dtd
+fcpxml/__init__.py   ──► reexporta a API pública
+```
+
+> Se você cria uma **nova ferramenta MCP**, o trabalho principal é em `fcpxml/`
+> (função pura + testes). O handler em `server.py` fica fino: validação de
+> caminho → `_parse_project` → chama a função → `_text_result`.