phpVirtualBox en Go — parte 2: migración con IA y OpenSpec

Antes de empezar: conoce el proyecto original en el artículo phpVirtualBox: gestiona VirtualBox desde el navegador.

En esta serie: Parte 1: phpVirtualBox, Echo y Vue · Parte 2: IA y OpenSpec · Parte 3: implementación y pruebas

Serie phpVirtualBox en Go — parte 2 de 3. Una migración fiable empieza con contratos y evidencias, no con una conversión automática de archivos. En esta parte, organizaremos la reimplementación propuesta en Go, Echo y Vue usando IA y OpenSpec.

Cómo migrar con IA: comportamiento primero, código después

La estrategia que propongo es incremental. Fije un commit del proyecto de referencia, registre el entorno de laboratorio y pida a la IA un mapa de las funcionalidades. Cada conclusión debe apuntar a archivos o documentación que la respalden. Donde no haya evidencia, la respuesta correcta es una duda que investigar, no una implementación inventada.

Un prompt inicial útil sería:

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.

El resultado esperado es una matriz de funcionalidades: qué existe, qué se preservará, qué quedará para después y qué pruebas demostrarán la compatibilidad. Esto evita la trampa de convertir archivos PHP en archivos Go sin entender las reglas que implementan.

No es obligatorio preservar cada endpoint interno de la interfaz antigua. Es obligatorio decidir qué comportamientos e integraciones deben permanecer compatibles. Esa decisión debe aparecer en la especificación antes de convertirse en código.

OpenSpec: convertir la migración en cambios revisables

OpenSpec organiza el trabajo por cambios con propuesta, especificaciones, diseño técnico y tareas. La documentación actual exige Node.js 20.19 o superior para la herramienta. En un repositorio aparte para el nuevo panel, la preparación es:

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

Seleccione la integración con su asistente durante la inicialización. El flujo documentado utiliza /opsx:explore, /opsx:propose, /opsx:apply e /opsx:archive; la grafía de los comandos puede variar según el asistente. Son acciones del asistente, no comandos Bash. Instalación y flujo oficiales de OpenSpec.

El primer cambio podría tener esta organización:

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

En la propuesta, explica el objetivo y lo que no se hará. En el diseño técnico, registra cómo la API conversa con VirtualBox y cómo se gestionarán las configuraciones y los secretos. En las especificaciones, describe los resultados observables. En las tareas, pon pasos pequeños que se puedan implementar y verificar.

Ejemplo de especificación para el primer MVP

Comenzaría con un panel autenticado, capaz de listar máquinas sin modificar el entorno. El ejemplo siguiente es una especificación propuesta para el nuevo proyecto, no una funcionalidad ya 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

Observa que cada escenario exige una evidencia: respuesta HTTP, campos devueltos, ausencia de escritura o comportamiento de la interfaz. “Funciona como PHP” es demasiado amplio para ser un criterio de aceptación útil.

Ejemplo de tasks.md: tareas que la IA puede ejecutar

## 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 trabajar con la IA, pide solo la siguiente tarea o un conjunto pequeño de tareas dependientes. Exige un resumen de los archivos modificados, pruebas ejecutadas y limitaciones. La herramienta no debe marcar como concluida una integración validada solo con mocks si el criterio exige un host real.

OpenSpec organiza el proceso, pero no sustituye la revisión, las pruebas ni el conocimiento del dominio. Una casilla marcada no es evidencia de funcionamiento.

Cómo dividir el trabajo sin perder el control

Un cambio debe aportar un comportamiento observable. En lugar de una tarea llamada “migrar el backend”, separa autenticación, inventario, operaciones y persistencia. Dentro de cada cambio, registra dependencias: la pantalla de inventario depende de un contrato, pero puede desarrollarse con un servidor simulado mientras se implementa el adaptador.

Si utilizas varios agentes, asigna archivos o módulos distintos y mantén un responsable del contrato compartido. No dejes que cada agente invente su propio formato de error o representación de VM. Los cambios en el contrato deben volver a la especificación y a las pruebas, no surgir silenciosamente durante la implementación.

Un prompt para la fase de ejecución:

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 compartido entre especificación, API e interfaz

Para mantener la serie coherente, el primer MVP utiliza un único host configurado previamente. GET /api/v1/vms no acepta direcciones SOAP arbitrarias. El contrato siguiente es una propuesta de diseño, no una API ya ofrecida por phpVirtualBox:

Escenario	Respuesta propuesta	Evidencia exigida
Consulta autorizada	200, objeto con lista vms.	Solo se permiten UUID, nombre y estado; una lista vacía no es un error.
Sin autenticación	401.	Ninguna llamada al adaptador SOAP.
Sin permiso	403.	Ninguna llamada al adaptador SOAP ni nombres de máquinas expuestos.
Servicio no disponible	502, código de error estable.	Detalles técnicos saneados solo en el servidor.
Plazo agotado	504.	Cancelación/límites de transporte y liberación de los recursos adquiridos.

Defina un sobre de error con code, message e request_id. La interfaz decide cómo mostrar el problema mediante el código estable, sin comparar frases traducidas. No devuelva credenciales, XML sin procesar ni stack traces. Los códigos HTTP anteriores son decisiones de este nuevo contrato, no códigos que el servicio SOAP prometa devolver.

Fijar herramientas y validar artefactos

La instalación anterior fija OpenSpec 1.14.1, versión consultada en esta revisión; registre también el commit del proyecto de referencia, la versión de Node y la salida de openspec --version. El perfil predeterminado incluye explore, propose, apply y archive; las acciones del flujo ampliado dependen del perfil elegido. En Codex, la documentación presenta la familia $openspec-propose, mientras que otros asistentes utilizan /opsx:propose. Siga lo que openspec init instalar para su cliente.

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

La validación verifica la estructura del cambio; no ejecuta pruebas de aplicación ni prueba compatibilidad con VirtualBox. No marque “host real aprobado” porque el validador terminó con éxito.

Evidencias que deben acompañar la revisión

• Commit de referencia y archivos que respaldan cada comportamiento conservado.
• Contrato aprobado, escenarios de rechazo y fixtures sin datos personales ni secretos.
• Comandos de prueba, resultado y distinción explícita entre simulación e integración real.
• Versión de VirtualBox probada, usuario de servicio y límites conocidos.
• Lista de lo que no se ejecutó, sin reemplazar vacíos por suposiciones.

Qué significa completar un cambio

La revisión debe verificar código, pruebas y documentación de forma conjunta. ¿Se implementaron los escenarios? ¿Los errores siguen estructurados? ¿Apareció algún secreto en los fixtures? ¿Se validó el comportamiento en el laboratorio cuando es necesario? Una prueba simulada no debe presentarse como integración real con VirtualBox.

Archiva el cambio solo después de la revisión y registra las limitaciones restantes. En la próxima parte, veremos cómo esta planificación se convierte en una secuencia de entregas: desde el primer ejecutable con Vue incorporado hasta operaciones de escritura, recuperación e implementación.

En esta serie: Parte 1: phpVirtualBox, Echo y Vue · Parte 2: IA y OpenSpec · Parte 3: implementación y pruebas