Spring Migrator to Quarkus

Extensión de Visual Studio Code que agrega el participante de chat @migrator para ejecutar migraciones de aplicaciones Spring Boot a Quarkus 3.x de forma autónoma, fase por fase, con compilación y commit automático por cada etapa completada.

La extensión trae empaquetados los prompts y la skill de migración, por lo que puede funcionar aunque el proyecto que estás migrando no tenga una carpeta .github.

Marketplace

• Visual Studio Marketplace: yemicanchari.spring-migrator-to-quarkus
• Extension ID: yemicanchari.spring-migrator-to-quarkus

Requisitos

• Visual Studio Code 1.90.0 o superior.
• GitHub Copilot Chat o un proveedor compatible con VS Code Language Model API.
• Maven (mvn) disponible en el PATH (para el modo autónomo).
• Git disponible en el PATH.
• Node.js 16.x o superior para desarrollo.

Instalación para desarrollo

1. Abre este repositorio en VS Code.
2. Instala dependencias:

npm install

3. Compila la extensión:

npm run compile

4. Presiona F5 para abrir una ventana Extension Development Host.

Flujo recomendado: migración autónoma

La forma más sencilla de usar la extensión es con los dos comandos principales:

Paso 1 — Inicializar

@migrator /init

Escanea todos los módulos Spring Boot detectados en el workspace y muestra un QuickPick para que selecciones el que quieres migrar. Al confirmar:

• Crea la carpeta {modulo}-migrate/ en la raíz del workspace.
• Crea la rama git migration/{modulo}.
• Guarda el estado inicial en {modulo}-migrate/.migration-state.json.

Si ya existe una migración en progreso, te pregunta si quieres retomar la anterior o iniciar una nueva.

Paso 2 — Migrar

@migrator /migrate

Ejecuta el orquestador que recorre las fases en este orden:

setup → assess → test → config → service → rest → rxjava → retrofit → infra → validate → summary

Para cada fase:

1. El LLM lee el código fuente original usando las herramientas del workspace.
2. Escribe los archivos migrados en {modulo}-migrate/ usando la herramienta workspace_write_file.
3. Compila con mvn clean compile -DskipTests.
4. Si compila: hace un commit automático [migrator] {fase}: migrate {modulo} y avanza.
5. Si falla: envía los errores de compilación al LLM para que los corrija y reintenta hasta 3 veces.
6. Al finalizar todas las fases, muestra un resumen con cuántas completó y los commits generados.

Si interrumpes el proceso, al volver a ejecutar /migrate retoma desde la última fase pendiente (las fases con estado done se saltan automáticamente).

Comandos disponibles

Orquestador (flujo autónomo)

Pasos individuales (control manual)

Puedes ejecutar cada fase de forma independiente si prefieres controlar el proceso paso a paso:

Pasos avanzados

Utilidades

Ejemplos

Flujo autónomo completo

@migrator /init

→ Aparece QuickPick con los módulos detectados. Seleccionas src/main/java/com/acme/orders. → Se crea orders-migrate/, rama migration/orders, y .migration-state.json.

@migrator /migrate

→ El orquestador ejecuta setup → assess → ... → summary. → Cada compilación exitosa genera un commit. Si falla, el LLM corrige y recompila.

Control manual por paso

@migrator /assess src/main/java/com/acme/orders

@migrator /service src/main/java/com/acme/orders/OrderService.java

@migrator /service-repository OrderService.java OrderRepository.java

@migrator /rxjava src/main/java/com/acme/orders/ReactiveOrderService.java

Usando alias exactos

@migrator /04b-migrate-service-repository src/main/java/com/acme/orders

Estado de migración

Cuando usas /init + /migrate, la extensión guarda el estado en {modulo}-migrate/.migration-state.json:

{
  "module": "orders",
  "sourcePath": "src/main/java/com/acme/orders",
  "targetFolder": "orders-migrate",
  "branch": "migration/orders",
  "startedAt": "2026-04-24T10:00:00Z",
  "phases": {
    "setup":  { "status": "done", "commitSha": "abc1234", "completedAt": "..." },
    "assess": { "status": "done", "commitSha": "def5678", "completedAt": "..." },
    "config": { "status": "in-progress", "attempts": 2 },
    "service": { "status": "pending", "attempts": 0 }
  }
}

Estados posibles por fase: pending, in-progress, done, failed.

Al ejecutar /migrate de nuevo, las fases con estado done se saltan y continúa desde la primera pendiente o fallida.

Herramientas del workspace

Cuando el LLM necesita información real del proyecto, dispone de estas herramientas:

Creación y modificación de archivos

Modo manual (pasos individuales):

• Solo se crean archivos nuevos mediante bloques migrator-artifacts en la respuesta del modelo.
• Los archivos existentes nunca se sobrescriben.
• Se rechazan rutas absolutas y rutas con ...

Modo orquestador (/migrate):

• El LLM usa workspace_write_file para escribir directamente en {modulo}-migrate/.
• Permite sobreescribir archivos ya creados en esa carpeta durante los reintentos de compilación.
• Nunca puede escribir fuera de la carpeta de migración.

Telemetría mínima (opt-in)

• Setting: springMigratorToQuarkus.telemetry.enabled (defecto: false)
• Si se activa, registra solo metadatos técnicos: nombre de comando/tool, duración, conteos y estado de ejecución.
• No se envía código fuente, rutas completas ni datos personales.
• Dashboard: paleta de comandos → Spring Migrator: Ver dashboard de telemetría.

Configuración de build del orquestador

• springMigratorToQuarkus.build.timeoutProfile: short (30s), medium (120s), long (300s).
• springMigratorToQuarkus.build.maxRetries: reintentos máximos por fase (default: 3).
• springMigratorToQuarkus.build.retryBackoffMs: backoff base entre reintentos (default: 2000 ms).

Desarrollo

npm run watch     # TypeScript en modo observación
npm run compile   # Compilación única
npm run lint      # ESLint
npm run test      # Tests unitarios

Después de modificar src/extension.ts, recarga la ventana con Developer: Reload Window.

Estructura principal

src/
├── extension.ts                  # Punto de entrada, registra @migrator y comandos
└── migrator/
    ├── engine.ts                 # Orquestador principal, /init, /migrate, loop compilación-commit
    ├── migration-state.ts        # Estado persistente por fase en .migration-state.json
    ├── tools.ts                  # Herramientas del workspace para el LLM
    ├── prompts.ts                # Construcción de mensajes y parseo de frontmatter
    ├── artifacts.ts              # Creación segura de archivos desde respuestas del modelo
    ├── workspace.ts              # Análisis del workspace (pom.xml, módulos Java)
    ├── security.ts               # Allowlist de comandos de terminal
    ├── constants.ts              # Definiciones de comandos, secuencia de fases, límites
    └── types.ts                  # Tipos TypeScript compartidos
resources/migration/
├── copilot-instructions.md       # Reglas globales de arquitectura (DDD, Java 21, etc.)
├── copilot-skills/migration-skill.md  # Skill de 11 pasos
└── prompts/                      # 18 prompts especializados (uno por fase)