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@latest
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.

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