phpVirtualBox em Go — parte 2: migração com IA e OpenSpec

Antes de começar: conheça o projeto original no artigo phpVirtualBox: gerencie o VirtualBox pelo navegador.

Nesta série: Parte 1: phpVirtualBox, Echo e Vue · Parte 2: IA e OpenSpec · Parte 3: implementação e testes

Série phpVirtualBox em Go — parte 2 de 3. Uma migração confiável começa com contratos e evidências, não com uma conversão automática de arquivos. Nesta parte, vamos organizar a reimplementação proposta em Go, Echo e Vue usando IA e OpenSpec.

Como migrar com IA: comportamento primeiro, código depois

A estratégia que proponho é incremental. Fixe um commit do projeto de referência, registre o ambiente de laboratório e peça à IA um mapa das funcionalidades. Cada conclusão deve apontar para arquivos ou documentação que a sustentem. Onde não houver evidência, a resposta correta é uma dúvida a investigar, não uma implementação inventada.

Um prompt inicial útil seria:

Analise o phpVirtualBox sem modificar arquivos.

Mapeie telas, endpoints, autenticação, integração SOAP
 e operações que alteram máquinas virtuais.

Para cada comportamento, indique os arquivos de referência.
Separe fatos verificados, dúvidas e propostas de melhoria.

Proponha um MVP somente leitura em Go + Echo + Vue.
Não implemente código e não execute ações em VMs.

O resultado esperado é uma matriz de funcionalidades: o que existe, o que será preservado, o que ficará para depois e quais testes demonstrarão a compatibilidade. Isso evita a armadilha de converter arquivos PHP em arquivos Go sem entender as regras que eles implementam.

Não é obrigatório preservar cada endpoint interno da interface antiga. É obrigatório decidir quais comportamentos e integrações precisam permanecer compatíveis. Essa decisão deve aparecer na especificação antes de virar código.

OpenSpec: transformar a migração em mudanças revisáveis

O OpenSpec organiza o trabalho por mudanças com proposta, especificações, desenho técnico e tarefas. A documentação atual exige Node.js 20.19 ou superior para a ferramenta. Em um repositório separado para o novo painel, a preparação é:

npm install -g @fission-ai/openspec@1.14.1
openspec init

Selecione a integração com seu assistente durante a inicialização. O fluxo documentado usa /opsx:explore, /opsx:propose, /opsx:apply e /opsx:archive; a grafia dos comandos pode variar conforme o assistente. Eles são ações do assistente, não comandos Bash. Instalação e fluxo oficiais do OpenSpec.

A primeira mudança poderia ter esta organização:

openspec/changes/painel-vms-somente-leitura/
├── proposal.md
├── design.md
├── specs/
│   └── inventario-vms/
│       └── spec.md
└── tasks.md

Na proposta, explique o objetivo e o que não será feito. No desenho técnico, registre como a API conversa com o VirtualBox e como configurações e segredos serão tratados. Nas especificações, descreva os resultados observáveis. Nas tarefas, coloque etapas pequenas que possam ser implementadas e verificadas.

Exemplo de especificação para o primeiro MVP

Eu começaria com um painel autenticado, capaz de listar máquinas sem modificar o ambiente. O exemplo abaixo é uma especificação proposta para o novo projeto, não uma funcionalidade já implementada:

## ADDED Requirements

### Requirement: Inventário protegido de máquinas virtuais
The system SHALL listar apenas máquinas autorizadas
para o usuário autenticado, sem alterar seu estado.

#### Scenario: Consulta autorizada
- **WHEN** um usuário autorizado solicita o inventário
- **THEN** a API retorna UUID, nome e estado das máquinas
- **AND** nenhuma operação de escrita é executada

#### Scenario: Requisição sem autenticação
- **WHEN** uma requisição anônima consulta o inventário
- **THEN** a API responde HTTP 401
- **AND** não divulga dados das máquinas

#### Scenario: Usuário sem permissão
- **WHEN** um usuário autenticado não possui acesso ao inventário
- **THEN** a API responde HTTP 403

#### Scenario: Timeout do serviço de virtualização
- **WHEN** a consulta excede o prazo configurado
- **THEN** a API responde HTTP 504 com erro estruturado
- **AND** a interface permite uma nova tentativa manual

Observe que cada cenário exige uma evidência: resposta HTTP, campos retornados, ausência de escrita ou comportamento da interface. “Funciona como o PHP” é amplo demais para ser um critério de aceitação útil.

Exemplo de tasks.md: tarefas que a IA consegue executar

## 1. Referência e contrato
- [ ] Registrar o commit PHP usado como referência.
- [ ] Documentar o contrato GET /api/v1/vms e seus erros.
- [ ] Criar fixtures sanitizadas para os cenários aceitos.

## 2. Backend
- [ ] Criar a estrutura Echo com configuração externa.
- [ ] Implementar autenticação e autorização do inventário.
- [ ] Implementar a consulta SOAP com timeout configurável.
- [ ] Garantir liberação das sessões utilizadas, inclusive em erros.
- [ ] Testar host indisponível, acesso negado e resposta inválida.

## 3. Frontend e distribuição
- [ ] Exibir máquinas, lista vazia, carregamento e erros no Vue.
- [ ] Incorporar os arquivos compilados com go:embed.
- [ ] Executar o binário fora da árvore do código-fonte.

## 4. Aceitação
- [ ] Comparar o inventário com o host real de laboratório.
- [ ] Comprovar que a consulta não dispara operações de escrita.
- [ ] Registrar resultados dos testes e limitações conhecidas.
- [ ] Revisar a mudança antes de arquivar a especificação.

Para trabalhar com a IA, peça apenas a próxima tarefa ou um conjunto pequeno de tarefas dependentes. Exija um resumo dos arquivos alterados, testes executados e limitações. A ferramenta não deve marcar como concluída uma integração validada somente com mocks se o critério exige um host real.

O OpenSpec organiza o processo, mas não substitui revisão, testes ou conhecimento do domínio. Uma caixa marcada não é evidência de funcionamento.

Como dividir o trabalho sem perder o controle

Uma mudança deve entregar um comportamento observável. Em vez de uma tarefa chamada “migrar o backend”, separe autenticação, inventário, operações e persistência. Dentro de cada mudança, registre dependências: a tela de inventário depende de um contrato, mas pode ser desenvolvida com um servidor simulado enquanto o adaptador é implementado.

Se utilizar vários agentes, atribua arquivos ou módulos distintos e mantenha um responsável pelo contrato compartilhado. Não deixe cada agente inventar seu próprio formato de erro ou representação de VM. Mudanças no contrato devem voltar à especificação e aos testes, não surgir silenciosamente durante a implementação.

Um prompt para a fase de execução:

Leia a proposta, o desenho técnico e os cenários desta mudança.
Implemente somente a próxima tarefa pendente autorizada.
Não altere o contrato para contornar um teste que falhou.
Não execute operações em infraestrutura de produção.
Adicione testes e registre os comandos e seus resultados.
Se faltar uma decisão, explique o bloqueio antes de inventá-la.
Só marque a tarefa concluída com evidência de aceitação.

Contrato compartilhado entre especificação, API e interface

Para manter a série consistente, o primeiro MVP usa um único host previamente configurado. GET /api/v1/vms não aceita endereço SOAP arbitrário. O contrato abaixo é uma proposta de projeto, não uma API já disponibilizada pelo phpVirtualBox:

Cenário	Resposta proposta	Evidência exigida
Consulta autorizada	200, objeto com lista vms.	Somente UUID, nome e estado permitidos; lista vazia não é erro.
Sem autenticação	401.	Nenhuma chamada ao adaptador SOAP.
Sem permissão	403.	Nenhuma chamada ao adaptador SOAP nem nomes de máquinas expostos.
Serviço indisponível	502, código de erro estável.	Detalhes técnicos sanitizados apenas no servidor.
Prazo excedido	504.	Cancelamento/limites de transporte e liberação dos recursos adquiridos.

Defina um envelope de erro com code, message e request_id. A interface decide como exibir o problema pelo código estável, não comparando frases traduzidas. Não devolva credenciais, XML bruto ou stack traces. Os códigos HTTP acima são escolhas deste novo contrato, não códigos que o serviço SOAP promete retornar.

Fixar ferramentas e validar artefatos

A instalação acima fixa OpenSpec 1.14.1, versão consultada nesta revisão; registre também o commit do projeto de referência, a versão do Node e a saída de openspec --version. O perfil padrão inclui explore, propose, apply e archive; ações do fluxo expandido dependem do perfil escolhido. No Codex, a documentação apresenta a família $openspec-propose, enquanto outros assistentes usam /opsx:propose. Siga o que openspec init instalar para seu cliente.

openspec --version
openspec validate painel-vms-somente-leitura --strict --no-interactive

A validação verifica a estrutura da mudança; não executa testes de aplicação nem prova compatibilidade com o VirtualBox. Não marque “host real aprovado” porque o validador terminou com sucesso.

Evidências que devem acompanhar a revisão

• Commit de referência e arquivos que sustentam cada comportamento preservado.
• Contrato aprovado, cenários de rejeição e fixtures sem dados pessoais ou segredos.
• Comandos de teste, resultado e distinção explícita entre simulação e integração real.
• Versão do VirtualBox testada, usuário de serviço e limites conhecidos.
• Lista do que não foi executado, sem substituir lacunas por suposições.

O que significa terminar uma mudança

A revisão precisa verificar código, testes e documentação em conjunto. Os cenários foram implementados? Os erros continuam estruturados? Algum segredo apareceu em fixtures? O comportamento foi validado no laboratório quando exigido? Um teste simulado não deve ser apresentado como integração real com o VirtualBox.

Arquive a mudança somente depois da revisão e registre as limitações restantes. Na próxima parte, veremos como esse planejamento se transforma em uma sequência de entregas: do primeiro executável com Vue incorporado até operações de escrita, recuperação e implantação.

Nesta série: Parte 1: phpVirtualBox, Echo e Vue · Parte 2: IA e OpenSpec · Parte 3: implementação e testes