jhonny-editor/code/engine/arquitetura/plano-primeira-etapa-scanner-e-mcp.md

Plano de Desenvolvimento — Primeira Etapa

Scanner e leitura da timeline via MCP

Status

Plano de desenvolvimento da primeira etapa. Este documento organiza a implementação futura; não autoriza a criação imediata de código sem que cada fase esteja preparada e validada.

Objetivo

Construir o primeiro fluxo funcional do sistema capaz de ler a timeline ativa do Premiere por meio do MCP e transformá-la em uma representação interna confiável.

Ao final desta etapa, o sistema deverá conseguir:

1. comunicar-se com o MCP;
2. verificar a disponibilidade do Premiere;
3. ler a sequência ativa, faixas e clipes;
4. converter respostas externas em objetos do domínio;
5. validar dados incompletos ou inválidos;
6. executar a descoberta por meio do Scanner;
7. registrar erros e informações relevantes;
8. testar todo o fluxo sem depender do Premiere real.

Limites da etapa

Incluído

• conexão e chamadas técnicas ao MCP;
• sessão e erros da integração;
• leitura da timeline, sequência, faixas e clipes;
• conversores de dados externos;
• entidades e objetos de valor necessários;
• contrato de acesso ao editor;
• contexto, pipeline e descoberta da timeline;
• configuração mínima do scanner;
• logs técnicos e de fluxo;
• testes unitários, de integração simulada e de conversores;
• fixtures baseadas em respostas reais do MCP.

Não incluído

• corte, exclusão ou movimentação de clipes;
• qualquer escrita no Premiere;
• plano de edição;
• decisão automática;
• transcrição;
• análise visual;
• análise de áudio;
• detecção de cenas;
• detecção de retakes;
• uso obrigatório de provider de IA;
• otimizações prematuras ou execução paralela.

Estrutura planejada

engine/
├── arquitetura/
│   └── documentação da arquitetura
├── scanner/
│   ├── coordenacao/
│   ├── contratos/
│   ├── modelos/
│   ├── configuracao/
│   └── descoberta/
├── integracoes/
│   └── premiere/
│       ├── cliente_mcp.py
│       ├── sessao_mcp.py
│       ├── erros_mcp.py
│       ├── leitura/
│       ├── conversores/
│       └── contratos/
├── dominio/
│   ├── entidades/
│   └── objetos_de_valor/
├── configuracao/
├── persistencia/
├── logging/
└── testes/

Fases de desenvolvimento

Fase 0 — Preparação e confirmação arquitetural

Objetivo: garantir que o desenho está coerente antes da implementação.

Atividades:

• revisar scanner.md, integracao-com-premiere.md e leitura-da-timeline-via-mcp.md;
• revisar a skill boas-praticas-oo.md;
• confirmar que todos os identificadores internos serão em PT-BR;
• definir os contratos antes das implementações concretas;
• confirmar que o scanner não terá dependência direta do MCP;
• identificar quais classes são realmente necessárias na primeira versão.

Entrega: arquitetura aprovada e sem responsabilidades sobrepostas.

Fase 1 — Descoberta da API real do MCP

Objetivo: conhecer o contrato externo antes de criar adaptadores definitivos.

Atividades:

• identificar como o MCP é iniciado;
• verificar como a conexão é estabelecida;
• listar as ferramentas disponíveis;
• identificar ferramentas para projeto, sequência, faixas e clipes;
• registrar argumentos, respostas e erros;
• observar formato dos identificadores e dos tempos;
• capturar respostas reais anonimizadas para fixtures;
• confirmar se a comunicação é síncrona ou assíncrona;
• confirmar se existe estado de sessão.

Regra: nomes de ferramentas e campos externos não serão inventados. Eles ficarão isolados na integração.

Entrega: inventário do MCP e conjunto inicial de fixtures reais.

Fase 2 — Contratos e modelos do domínio

Objetivo: definir as interfaces internas antes dos adaptadores.

Contratos:

• ContratoDeAcessoAoEditor;
• contrato de etapa do scanner;
• contrato de conversor, quando necessário.

Entidades:

• Projeto;
• Sequencia;
• Timeline;
• Faixa;
• Clipe.

Objetos de valor:

• IntervaloDeTempo;
• TipoDeFaixa;
• TipoDeMidia;
• identificadores internos e externos, se necessário.

Invariantes mínimas:

• intervalo não pode iniciar antes de zero;
• fim não pode ser anterior ao início;
• identificadores devem ser preservados;
• posição na timeline e posição na origem são distintas;
• clipe pode estar offline sem invalidar toda a timeline;
• nome não é identificador único.

Entrega: modelo interno independente de MCP e editor.

Fase 3 — Cliente e sessão MCP

Objetivo: encapsular a comunicação técnica externa.

Classes:

• ClienteMCP;
• SessaoMCP;
• ErroMCP;
• ErroDeConexaoMCP;
• ErroDeFerramentaMCP;
• ErroDeRespostaMCP;
• FerramentaMCPNaoEncontrada.

Responsabilidades:

• conectar e desconectar;
• informar estado da conexão;
• chamar ferramentas;
• controlar timeout;
• retornar resposta bruta;
• traduzir falhas técnicas em erros específicos;
• registrar logs técnicos.

Restrições:

• não criar entidades de domínio;
• não conhecer timeline, clipe, cena ou retake;
• não decidir qual ferramenta usar para uma regra de negócio;
• não misturar leitura e escrita.

Entrega: comunicação técnica testável com cliente simulado.

Fase 4 — Leitura estruturada do Premiere

Objetivo: oferecer operações de alto nível para o restante do sistema.

Classes iniciais:

• AcessoAoEditor;
• AcessoATimeline;
• AcessoAClipes.

Operações iniciais:

• obter timeline ativa;
• obter sequência ativa;
• obter faixas;
• obter clipes;
• obter detalhes de um clipe.

Essas classes poderão começar com uma fachada simples e ser divididas somente quando houver crescimento real de responsabilidade.

Entrega: leitura sem que o scanner conheça nomes de ferramentas MCP.

Fase 5 — Conversão e validação

Objetivo: transformar respostas externas em objetos internos confiáveis.

Classes:

• ConversorDeTimeline;
• ConversorDeFaixas;
• ConversorDeClipes.

Atividades:

• normalizar nomes de campos;
• converter tempos e identificadores;
• aplicar valores padrão seguros;
• validar campos obrigatórios;
• preservar campos externos relevantes;
• tratar tipos desconhecidos;
• diferenciar resposta incompleta de timeline vazia;
• gerar erros de validação estruturados.

Entrega: timeline de domínio construída a partir de fixtures externas.

Fase 6 — Núcleo do scanner

Objetivo: executar a descoberta por meio do fluxo arquitetural definido.

Classes:

• ContextoDeAnalise;
• Analisador;
• ResultadoDaAnalise;
• StatusDaAnalise;
• ErroDeAnalise;
• DescobertaDaTimeline;
• PipelineDoScanner;
• AnalisadorDeTimeline.

Fluxo:

AnalisadorDeTimeline
    ↓
ContextoDeAnalise
    ↓
PipelineDoScanner
    ↓
DescobertaDaTimeline
    ↓
ContratoDeAcessoAoEditor
    ↓
Timeline do domínio
    ↓
Contexto atualizado

Na primeira versão, o pipeline poderá conter somente DescobertaDaTimeline.

Entrega: scanner capaz de retornar o contexto com a timeline lida.

Fase 7 — Testes e integração simulada

Objetivo: garantir comportamento sem depender do Premiere real.

Implementar:

• AcessoAoEditorSimulado;
• fixtures de projeto, sequência, faixas e clipes;
• testes do cliente MCP;
• testes dos acessos de leitura;
• testes dos conversores;
• testes das entidades e objetos de valor;
• testes do pipeline;
• testes da descoberta;
• testes de integração simulada.

Cenários obrigatórios:

• timeline válida;
• timeline vazia;
• nenhuma sequência ativa;
• sequência sem clipes;
• mídia offline;
• resposta incompleta;
• intervalo inválido;
• ferramenta inexistente;
• timeout;
• MCP indisponível;
• campos adicionais desconhecidos.

Entrega: suíte automatizada reproduzível.

Fase 8 — Validação com Premiere real

Objetivo: confirmar o fluxo contra o ambiente real.

Atividades:

• conectar ao MCP real;
• listar ferramentas e comparar com o inventário;
• ler projeto e sequência reais;
• comparar resposta real com fixtures;
• validar faixas e clipes;
• testar projeto vazio;
• testar mídia offline;
• verificar logs sem dados sensíveis;
• confirmar que nenhuma ferramenta de escrita foi chamada.

Entrega: relatório de validação da leitura real.

Critérios de conclusão

A primeira etapa estará concluída quando:

• o scanner depender apenas de contratos internos;
• o MCP estiver isolado no módulo de integração;
• a timeline ativa puder ser lida do Premiere;
• faixas e clipes forem convertidos para o domínio;
• intervalos da timeline e da origem forem preservados separadamente;
• mídia offline for representada sem interromper toda a leitura;
• timeline vazia for tratada como resultado válido quando apropriado;
• erros técnicos e de validação forem distinguíveis;
• o fluxo puder ser executado com integração simulada;
• os testes automatizados estiverem passando;
• os logs forem úteis e seguros;
• nenhuma alteração for feita na timeline;
• todos os identificadores internos respeitarem PT-BR;
• a implementação estiver aderente à skill de boas práticas OO.

Ordem resumida

Arquitetura
    ↓
API real do MCP
    ↓
Contratos e domínio
    ↓
ClienteMCP
    ↓
AcessoAoEditor
    ↓
Conversores
    ↓
Contexto e pipeline
    ↓
DescobertaDaTimeline
    ↓
Testes simulados
    ↓
Validação com Premiere real

Regra final

O MCP é o mecanismo de comunicação com o editor. O scanner é o módulo que organiza a descoberta. O domínio representa os dados. Os conversores isolam formatos externos. Nenhuma dessas responsabilidades deve ser concentrada em uma única classe.