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,84 @@
+# 03 — Camada MCP (`server.py`) — 62 ferramentas
+
+`server.py` (3824 linhas) é a camada de transporte. Não tem lógica de timeline —
+mapeia nome → handler e delega ao Engine. O dispatch é um dicionário
+`TOOL_HANDLERS` (padrão de despacho, sem cadeias gigantes de if/elif).
+
+## Helpers centrais (use-os, não reinvente)
+
+| Helper | Linha | Função |
+|--------|------:|--------|
+| `_check_json_depth()` | 83 | Rejeita payloads além de 50 níveis |
+| `_validate_filepath()` | 103 | Sandbox de entrada |
+| `_validate_output_path()` | 149 | Sandbox de saída |
+| `_format_clip_table()` | 245 | Renderização de tabela |
+| `_markdown_table()` | 259 | Renderização de tabela markdown |
+| `_parse_project()` | 319 | Parseia FCPXML → `(tree, timeline, project)`; quase todos os handlers começam aqui |
+| `_resolve_io_paths()` | 357 | Validação de caminho de entrada/saída |
+| `_setup_modifier()` | 390 | Prepara modifier com validação |
+| `_setup_generator()` | 414 | Prepara generator com validação |
+| `_parse_timestamp_parts()` | 433 | Parse de timestamps (min:seg, H:MM:SS, SMPTE) |
+| `_detect_flash_frames/gaps/duplicate_groups()` | 1667+ | Detectores de QC |
+
+## As 62 ferramentas por categoria
+
+### Timeline & análise (Projeto)
+`list_projects`, `analyze_timeline`, `list_clips`, `list_markers`, `list_connected_clips`,
+`list_compound_clips`, `list_library_clips`, `list_roles`, `list_keywords`, `list_effects`.
+
+### QC e detecção
+`find_short_cuts`, `find_long_clips`, `analyze_pacing`, `detect_flash_frames`,
+`detect_duplicates`, `detect_gaps`, `validate_timeline`, `detect_silence_candidates`,
+`detect_media_silence`, `remove_silence_candidates`, `remove_media_silence`, `detect_beats`.
+
+### Edição
+`add_marker`, `batch_add_markers`, `trim_clip`, `reorder_clips`, `add_transition`,
+`change_speed`, `delete_clips`, `split_clip`, `insert_clip`, `fix_flash_frames`,
+`rapid_trim`, `fill_gaps`, `add_audio`, `create_compound_clip`, `flatten_compound_clip`.
+
+### Geração
+`auto_rough_cut`, `generate_montage`, `generate_ab_roll`, `list_templates`, `apply_template`.
+
+### Beats / markers importados
+`import_beat_markers`, `snap_to_beats`, `import_srt_markers`, `import_transcript_markers`.
+
+### Roles
+`assign_role`, `filter_by_role`, `export_role_stems`.
+
+### Transcrição & edição por transcrição
+`transcribe_media`, `edit_by_transcript`, `remove_filler_words`.
+
+### Diferenciação
+`diff_timelines`.
+
+### Export / relink
+`export_edl`, `export_csv`, `export_resolve_xml`, `export_fcp7_xml`, `relink_media`.
+
+### Reformat
+`reformat_timeline`.
+
+### Live (macOS)
+`push_to_fcp`, `list_fcp_libraries`.
+
+---
+
+## Padrão de handler (a forma de fazer)
+
+```python
+async def handle_<nome>(arguments: dict):
+    tree, timeline, project = _parse_project(arguments)   # 1. parseia
+    # ...opera com o Engine (parser/writer/rough_cut/export)...
+    return _text_result(text)                             # 2. devolve
+```
+
+Regras:
+- Todo handler valida caminho com `_validate_filepath`/`_validate_output_path`.
+- Saídas sempre com sufixo `_modified`, `_chapters`, etc. — original nunca é tocado.
+- Cada handler tem o seu `async def handle_<name>(arguments: dict)`.
+- Sempre retornam via `_text_result(text)` (envolve o texto em `TextContent` MCP).
+
+## Para adicionar uma ferramenta nova
+1. Escrever a função no módulo do Engine (`fcpxml/…`) + testes.
+2. Criar `handle_<nome>` em `server.py` seguindo o padrão acima.
+3. Registrar no dicionário `TOOL_HANDLERS`.
+4. Rodar `./Engine/run_after_fix.sh`.