Microservice Migration Orchestrator

CLI en Node.js para orquestar una migración de microservicio mediante una línea de producción por estaciones. Genera evidencia local para copiar manualmente en Jira, además de gestionar endpoints, versionado, documentación técnica, controles de calidad y el reporte final de migración.

El CLI realiza peticiones HTTP de lectura (GET) únicamente para validar endpoints. No realiza llamadas a la API de Jira: comment genera el texto en consola y en un archivo local para copiarlo manualmente en la tarea corporativa.

Contenido

• Requisitos e instalación
• Inicio rápido
• Modo Zero-Config y pipeline one-click
• Línea de producción por estaciones
• Comandos CLI
• Motor de paridad API
• Variables de entorno
• Artefactos y evidencia
• Asistente interactivo
• Desarrollo
• Seguridad

Requisitos e instalación

• Node.js 18 o superior.
• Acceso al microservicio y a su definición OpenAPI/Swagger o colección Postman para las estaciones de endpoints.
• No se requieren credenciales ni acceso a la API de Jira. El texto se copia manualmente en la tarea corporativa.
• Maven o Gradle únicamente para ejecutar cobertura JaCoCo.
• Acceso a SonarQube únicamente para consultar métricas de calidad.

Ejecutar sin instalación

Usa npx para ejecutar la última versión publicada:

npx microservice-migration-orchestrator-cli --help

El binario instalado se denomina migration-cli, por lo que también puedes invocarlo explícitamente:

npx --package microservice-migration-orchestrator-cli migration-cli --help

Instalación global

npm install --global microservice-migration-orchestrator-cli

migration-cli --help

Desarrollo local

git clone https://github.com/jaimegarfia/Microservice-migration-orchestrator.git
cd Microservice-migration-orchestrator
npm install
npm test
npm start

Inicio rápido

Para ejecutar toda la línea de producción con la mínima configuración:

migration-cli run ./auth-service

# Incluye pruebas POST y paridad si ya conoces la URL migrada.
migration-cli run ./auth-service \
  --post-base-url https://api-migrada.example.com

También puedes ejecutar cada estación individualmente:

# Estación 0: genera el checklist y el workflow de IDE.
migration-cli init auth-service --jira-issue EVOLCRE4-1234

# Tras confirmar cada gateway, genera el texto para copiarlo manualmente en Jira.
migration-cli comment 0 ./auth-service

# Regenera exclusivamente el workflow para Axet, Cursor o Copilot.
migration-cli workflow ./auth-service

# Estación 0: toma la baseline de la API antes de migrar.
migration-cli endpoints --pre auth-service --source docs/openapi.yaml

# Estación 1: convierte Maven si aplica e inicia OpenRewrite en segundo plano.
migration-cli maven-to-gradle ./auth-service
migration-cli rewrite ./auth-service
migration-cli status ./auth-service
migration-cli version --bump patch ./auth-service
migration-cli readme ./auth-service

# Estación 2: genera JaCoCo y consulta SonarQube si está configurado.
migration-cli coverage ./auth-service
migration-cli sonar ./auth-service

# Estación 3: prueba la API migrada y compara con PRE.
migration-cli endpoints --post auth-service \
  --source docs/openapi.yaml \
  --base-url https://api-migrada.example.com

# Consolida la evidencia de todas las estaciones.
migration-cli summary auth-service ./auth-service

Ejecuta migration-cli <comando> --help para consultar ejemplos, flags y variables de entorno específicas de cada comando.

Modo Zero-Config y pipeline one-click

run es la ruta recomendada para automatizar una migración completa. Recibe la ruta del microservicio, o usa el directorio actual:

migration-cli run [microservicePath] [opciones]

Secuencia ejecutada:

1. Estación 0: genera el checklist local y el workflow Markdown para IDEs asistidos por IA. --jira-issue puede conservar una referencia local opcional, sin conexión con Jira.
2. Estación 0: detecta una definición OpenAPI, Swagger o Postman y genera la baseline PRE.
3. Estación 1: convierte automáticamente Maven a Gradle si detecta pom.xml sin build.gradle, ejecuta OpenRewrite, incrementa la versión (patch por defecto) y genera el README técnico.
4. Estación 2: inicializa y analiza coverage-orchestrator-cli-new, ejecuta cobertura JaCoCo y consulta SonarQube.
5. Estación 3: con --post-base-url, ejecuta POST, el motor de paridad y el resumen maestro.

Opciones principales:

migration-cli run ./auth-service \
  --source docs/openapi.yaml \
  --base-url https://api-original.example.com \
  --post-base-url https://api-migrada.example.com \
  --bump minor \
  --timeout 15000

El pipeline es tolerante a fallos: una definición ausente, JaCoCo no disponible, SonarQube sin configurar o un error de un paso se informa como [WARNING]; las estaciones posteriores y la generación del resumen continúan. Los problemas se reflejan en los artefactos de evidencia y el panel final.

Auto-descubrimiento de API

Sin --source, el CLI explora la raíz del microservicio, docs/ y postman/ para archivos .json, .yaml o .yml cuyo nombre contenga swagger u openapi, además de colecciones JSON ubicadas en postman/.

• En run no interactivo se usa la primera coincidencia ordenada y se registra una advertencia si hay varias.
• En el wizard se presenta un selector navegable con flechas cuando hay varias coincidencias.
• Si no existe ninguna definición en el wizard, se solicita de forma amistosa una ruta local o URL remota.
• En modo no interactivo, la ausencia de fuente no detiene el pipeline: omite la estación de endpoints y registra [WARNING].

Línea de producción por estaciones

| Estación | Objetivo | Comandos | | --- | --- | --- | | 0 — Preparación | Generar checklist, workflow de IDE y preservar el contrato de API previo. | init, workflow, endpoints --pre, comment 0 | | 1 — Migración | Convertir Maven a Gradle cuando aplique, ejecutar OpenRewrite, versionar el microservicio y producir su README técnico. | maven-to-gradle, rewrite, version, readme | | 2 — Calidad | Evaluar cobertura JaCoCo y métricas de SonarQube. | coverage, sonar | | 3 — Paridad | Probar la API migrada, comparar PRE/POST y consolidar el resultado. | endpoints --post, summary | | 4 — Entrega | Desplegar en CUA/PRO y tramitar CAB. | Evidencia y proceso operativo externo |

Estación 0 — Preparación

init no realiza llamadas a Jira ni necesita credenciales. --jira-issue es opcional y sólo sirve para conservar una referencia local de la tarea corporativa:

migration-cli init auth-service --jira-issue EVOLCRE4-1234
migration-cli init auth-service --jira-issue \
  https://jira.example.com/browse/EVOLCRE4-1234

Si no se proporciona una referencia, init genera directamente el checklist local:

.axetrules/history/jira-tasks-<microservicio>.md

Además, init genera o actualiza el workflow interactivo micro-migration.md bajo .axetrules/workflows/ para Axet, Cursor, Copilot y otros IDEs asistidos por IA. El workflow guía a la IA por las estaciones e incorpora un protocolo Self-Healing: ante errores de compilación Java, sintaxis, dependencias Maven/Gradle o tests, analiza el log, corrige el proyecto y reintenta de manera autónoma. Sólo escala a una persona tras 3 reintentos fallidos consecutivos del mismo problema, o inmediatamente ante credenciales, red/VPN/proxy, permisos o ausencia/incompatibilidad de JDK 17.

Tras completar una estación, migration-cli comment <0|1|2|3> . genera el texto de evidencia en consola y en un archivo local para copiarlo manualmente en Jira.

Puede regenerarse sin crear tareas ni checklist:

migration-cli workflow ./auth-service
migration-cli workflow . --name auth-service

Durante init, el CLI también crea o actualiza .gitignore mediante un bloque gestionado e idempotente. Conserva todas las reglas previas del repositorio y protege archivos locales, credenciales, evidencias y artefactos de Axet:

# Migration Orchestrator & Axet IDE Ignored Files
.env
.env.local
.env.*.local
.axetrules/
.axet/
micro-migration.md
rewriter.yml
zordon/

El bloque se identifica con delimitadores Migration Orchestrator & Axet IDE Ignored Files; las ejecuciones posteriores lo actualizan sin duplicarlo ni modificar reglas ajenas.

La baseline PRE ejecuta únicamente endpoints GET, conserva status, tiempo de respuesta, hash SHA-256 y un fragmento limitado de payload:

migration-cli endpoints --pre auth-service --source docs/openapi.yaml

La fuente de endpoints se detecta automáticamente en raíz, docs/ y postman/. Se admiten nombres que contengan swagger u openapi con extensión JSON/YAML, además de colecciones JSON dentro de postman/. El wizard permite elegir cuando hay varias fuentes.

También puede indicarse manualmente:

migration-cli endpoints --pre auth-service \
  --source postman/collection.json \
  --base-url https://api.example.com \
  --timeout 15000

Estación 1 — Maven a Gradle, OpenRewrite, versionado y README técnico

Cuando un proyecto contiene pom.xml y no tiene build.gradle, migration-cli run intenta la conversión Maven → Gradle automáticamente antes de OpenRewrite. También puede ejecutarse de forma explícita:

migration-cli maven-to-gradle ./auth-service

El conversor analiza coordenadas Maven, propiedades Java, dependencias, scopes, exclusiones, BOMs, repositorios y plugins. Genera build.gradle (Groovy), gradle.properties, settings.gradle, gradle/sonar.gradle y gradle/googleArtifactory.gradle cuando son necesarios. Incluye soporte para Spring Boot, JaCoCo, Failsafe/integrationTest, SonarQube y Google Artifact Registry.

También instala el Gradle Wrapper completo y valida el resultado mediante gradlew compileJava. Por defecto conserva pom.xml, .mvn/ y target/ para una convivencia temporal de ambos sistemas. Una vez validada la transición, puede eliminarse Maven explícitamente:

migration-cli maven-to-gradle ./auth-service --cutover

--cutover elimina pom.xml, .mvn/ y target/ sólo después de que la validación Gradle haya finalizado correctamente.

Para proyectos Gradle, ejecuta la receta upgrade.zordon.carre4 mediante OpenRewrite:

migration-cli rewrite ./auth-service

El comando crea rewriter.yml si no existe, inyecta temporalmente el plugin org.openrewrite.rewrite 6.19.0, la dependencia de receta y el bloque activeRecipe("upgrade.zordon.carre4"). Después lanza gradlew.bat rewriteRun --no-daemon en Windows o ./gradlew rewriteRun --no-daemon en Unix/macOS como proceso desacoplado y devuelve inmediatamente [RUNNING] con el PID y una estimación de 3–8 minutos. Los cambios aplicados por OpenRewrite se conservan y el worker restaura la configuración temporal del build al terminar.

Consulta el progreso cada 15–20 segundos:

migration-cli rewrite ./auth-service
migration-cli status ./auth-service

La ejecución persiste .axet/rewrite.pid, .axet/rewrite-state.json y .axet/rewrite.log. status muestra el PID, los segundos transcurridos y las últimas líneas del log mientras sigue activa; al finalizar devuelve [SUCCESS], [ERROR DE CONFIGURACIÓN] (autocorregible) o [ERROR DE ENTORNO] (JDK, red, credenciales o permisos). Puede sobrescribirse la dependencia de receta con REWRITE_RECIPE_DEPENDENCY.

Incrementa versiones consistentes en pom.xml, gradle.properties, build.gradle, build.gradle.kts y/o sonar-project.properties:

migration-cli version --bump patch ./auth-service
migration-cli version --bump minor ./auth-service
migration-cli version --bump snapshot ./auth-service

| Tipo | Resultado | | --- | --- | | patch | 1.0.0 → 1.0.1 | | minor | 1.0.0 → 1.1.0 | | snapshot | 1.0.0 → 1.0.1-SNAPSHOT |

Genera o actualiza el README técnico del microservicio:

migration-cli readme ./auth-service

El generador detecta, cuando están presentes, tecnologías Java/Kotlin, Spring Boot, Maven/Gradle, controladores REST, entidades JPA, configuración, persistencia y mensajería. La sección gestionada usa marcadores migration-cli:readme, preservando el contenido manual fuera de ellos.

Estación 2 — Cobertura y calidad

migration-cli coverage integra JaCoCo con coverage-orchestrator-cli-new:

migration-cli coverage ./auth-service

El comando ejecuta, en este orden:

1. npx coverage-orchestrator-cli-new init, que instala .axetrules/workflows/unit-tests.md.
2. Tests e informe JaCoCo:
   • Maven: mvn test jacoco:report.
   • Gradle: gradlew.bat test jacocoTestReport --no-daemon en Windows, o ./gradlew test jacocoTestReport --no-daemon en Unix.
3. npx coverage-orchestrator-cli-new analyze, que procesa el XML y actualiza .coverage-cache.json.
4. La evidencia local y el Quality Gate de líneas de 60%.

Para trabajar una misión concreta de cobertura, ejecuta npx coverage-orchestrator-cli-new next, implementa los tests JUnit 5/Mockito indicados y repite JaCoCo → analyze → next hasta alcanzar el umbral o completar las misiones.

Consulta las métricas de SonarQube:

SONAR_HOST_URL=https://sonar.example.com \
SONAR_TOKEN=<token> \
migration-cli sonar ./auth-service

La clave del proyecto debe estar declarada como sonar.projectKey en sonar-project.properties.

| Métrica | Umbral | | --- | --- | | Code Smells | Menos de 30 | | Bugs | 0 | | Hotspots de seguridad | 0 |

Sin credenciales o configuración de SonarQube, el comando genera evidencia con estado not-configured sin realizar llamadas remotas.

Estación 3 — Paridad API y resumen maestro

Ejecuta la API migrada y la compara contra el baseline PRE más reciente del mismo microservicio:

migration-cli endpoints --post auth-service \
  --source docs/openapi.yaml \
  --base-url https://api-migrada.example.com

Después consolida la evidencia:

migration-cli summary auth-service ./auth-service

El segundo argumento de summary es opcional; permite indicar la ruta del microservicio para verificar README y archivos de versión.

Comandos CLI

| Comando | Descripción | | --- | --- | | migration-cli | Inicia el asistente interactivo. | | migration-cli init [microserviceName] --jira-issue <claveOUrl> | Conserva opcionalmente una referencia local de la tarea corporativa y genera el checklist. Sin argumento inicia el asistente. | | migration-cli comment <stationNumber> [microservicePath] | Genera en consola y en un archivo local el texto Markdown de la estación para copiarlo manualmente en Jira. | | migration-cli run [microservicePath] | Pipeline One-Click Zero-Config de Estaciones 0 a 3, tolerante a fallos. | | migration-cli workflow [microservicePath] [--name <microserviceName>] | Genera o actualiza micro-migration.md para Axet y otros IDEs asistidos por IA. | | migration-cli endpoints --pre <microserviceName> | Captura la baseline de endpoints GET previa. | | migration-cli endpoints --post <microserviceName> | Ejecuta GET tras migración y analiza paridad. | | migration-cli maven-to-gradle [microservicePath] [--cutover] | Convierte Maven a Gradle, instala Wrapper y valida compileJava; --cutover elimina Maven tras validar. | | migration-cli rewrite [microservicePath] | Inicia OpenRewrite upgrade.zordon.carre4 en segundo plano y devuelve PID/estado [RUNNING]. | | migration-cli status [microservicePath] | Consulta el proceso OpenRewrite: PID, tiempo, últimas líneas de log y estado terminal. | | migration-cli version --bump <tipo> [microservicePath] | Actualiza versiones de build y Sonar. | | migration-cli readme [microservicePath] | Genera README técnico del microservicio. | | migration-cli coverage [microservicePath] | Ejecuta JaCoCo y evalúa cobertura. | | migration-cli sonar [microservicePath] | Consulta SonarQube y evalúa su Quality Gate. | | migration-cli summary <microserviceName> [microservicePath] | Genera el reporte maestro. |

Ayuda integrada

Todos los comandos incluyen ayuda contextual:

migration-cli --help
migration-cli endpoints --help
migration-cli version --help
migration-cli sonar --help

La ayuda muestra uso, argumentos, flags, ejemplos, archivos producidos y variables de entorno relevantes.

Flags de endpoints

| Flag | Uso | | --- | --- | | --pre | Genera evidencia previa a migración. | | --post | Ejecuta la comparación posterior contra el último PRE. | | --source <rutaOUrl> | Definición OpenAPI, Swagger o colección Postman local/remota. | | --base-url <url> | URL base si la definición no declara servidor o usa URLs relativas. | | --auth-token <token> | Token Bearer para endpoints; tiene prioridad sobre AUTH_TOKEN. | | --timeout <milisegundos> | Timeout por endpoint. |

Debe proporcionarse una y sólo una fase: --pre o --post.

Motor de paridad API

El motor de Estación 3 compara endpoint por endpoint los artefactos endpoints-pre.json y endpoints-post.json.

Para cada respuesta se almacena:

• ruta del endpoint;
• status HTTP;
• tiempo de respuesta en milisegundos;
• responseHash: SHA-256 del payload de texto;
• fragmento de payload limitado;
• error, cuando la petición no se puede completar.

Estados de comparación

| Estado | Criterio | | --- | --- | | 🟢 MATCH | Mismo status HTTP y mismo responseHash. | | 🟡 WARNING | Mismo status con hash distinto, latencia que varía más de 50%, o endpoint nuevo. | | 🔴 BREAKING CHANGE | Cambio de status HTTP o endpoint no disponible tras la migración. |

El resultado se escribe en parity-report.md con una tabla de status PRE/POST, tiempos y motivo. El estado global es:

• PASSED: todos los endpoints son MATCH.
• WARNING: no hay cambios rompientes, pero existe alguna advertencia.
• FAILED: existe al menos un BREAKING CHANGE.

El hash compara el payload textual recibido. Si el endpoint devuelve campos dinámicos (fechas, UUIDs, tokens o trazas), puede producir un WARNING aunque el contrato funcional siga siendo compatible.

Variables de entorno

Copia el archivo de ejemplo y completa sólo las variables necesarias:

cp .env.example .env

El CLI no carga automáticamente archivos .env; exporta las variables desde tu shell, tu herramienta de secretos o el entorno de CI/CD.

Jira y comentarios manuales

No se configura ninguna variable de Jira. El CLI no autentica contra Jira, no valida incidencias y no realiza peticiones HTTP para publicar comentarios.

--jira-issue acepta opcionalmente una clave o URL para conservar una referencia local durante la ejecución, pero comment no la necesita ni se guarda en .env. Para generar el texto que se copiará en Jira:

migration-cli comment 0 ./auth-service

El comando imprime el contenido y lo guarda en:

.axetrules/history/<timestamp>/jira-comment-station-0.md

La Estación 0 incluye las instrucciones corporativas para obtener tokens ATLAS/AGORA y el marcador para adjuntar capturas de los endpoints PRE. El resto de estaciones incluye el resumen de sus artefactos y marcadores para adjuntar las evidencias correspondientes.

Endpoints

| Variable | Descripción | | --- | --- | | AUTH_TOKEN | Token OAuth2/Bearer opcional para solicitudes GET. --auth-token tiene prioridad. | | AUTH_PROVIDER | Proveedor automático: ATLAS, AGORA o CUSTOM. | | ATLAS_CLIENT_ID, ATLAS_CLIENT_SECRET | Reservados para la configuración ATLAS del proyecto. | | AGORA_CLIENT_ID, AGORA_CLIENT_SECRET | Reservados para la configuración AGORA del proyecto. | | ATLAS_TOKEN_URL, AGORA_TOKEN_URL | Opcionales; sobrescriben la URL OAuth2 por defecto. | | ATLAS_AUTH_BASIC, AGORA_AUTH_BASIC | Opcionales; sobrescriben la cabecera Basic OAuth2 por defecto. |

Si no se proporciona --auth-token ni AUTH_TOKEN, el CLI obtiene un token OAuth2 automáticamente cuando AUTH_PROVIDER=ATLAS o AUTH_PROVIDER=AGORA, y lo inyecta como Authorization: Bearer <token> en todos los GET PRE/POST. El token se envía sólo en cabecera y nunca se persiste en la evidencia.

SonarQube

| Variable | Descripción | | --- | --- | | SONAR_HOST_URL | URL base de la instancia SonarQube. | | SONAR_TOKEN | Token Bearer para consultar la API de SonarQube. |

Además se requiere sonar.projectKey en sonar-project.properties. El token no se escribe en los reportes.

Artefactos y evidencia

Toda la evidencia local se guarda bajo .axetrules/history/, directorio excluido por .gitignore:

.axetrules/
└── history/
    ├── jira-tasks-auth-service.md
    └── <timestamp>/
        ├── endpoints-pre.json
        ├── endpoints-post.json
        ├── parity-report.md
        ├── station2-quality.json
        └── migration-summary.md

| Artefacto | Productor | Contenido | | --- | --- | --- | | .gitignore (bloque gestionado) | init | Ignora credenciales, evidencia, workflows y artefactos locales de migración/Axet. | | .axet/rewrite.pid, .axet/rewrite-state.json, .axet/rewrite.log | rewrite | PID, estado, salida y diagnóstico de la reescritura asíncrona. | | .coverage-cache.json | coverage-orchestrator-cli-new analyze | Estado y prioridades de las misiones de cobertura. | | jira-tasks-<servicio>.md | init sin incidencia vinculada | Checklist local de migración. | | endpoints-pre.json | endpoints --pre | Baseline de endpoints GET antes de migrar. | | endpoints-post.json | endpoints --post | Resultados GET sobre la API migrada. | | parity-report.md | endpoints --post | Comparativa PRE/POST y resultado de paridad. | | station2-quality.json | coverage / sonar | Cobertura JaCoCo, Sonar y Quality Gates. | | migration-summary.md | summary | Panel consolidado de las estaciones. |

summary localiza los artefactos más recientes para cada tipo, aunque se hayan generado en timestamps distintos.

Asistente interactivo

Ejecuta sin argumentos:

migration-cli

init no crea archivos .env ni .env.local. Las variables necesarias deben exportarse desde el shell, configurarse en el entorno de CI/CD o gestionarse mediante una herramienta de secretos antes de capturar endpoints o consultar SonarQube.

El menú principal muestra:

1. 🚀 Ejecutar Migración Completa — inicia el pipeline run.
2. 📋 Gestionar Tareas — Estación 0.
3. 🔍 Analizar Endpoints y Paridad — Estaciones 0 y 3.
4. 🛠️ Versionado y Documentación — Estación 1.
5. 🧪 Cobertura y Calidad — Estación 2.
6. ❌ Salir.

Jira se gestiona manualmente: comment genera el texto y el archivo Markdown local para copiarlo en la tarea corporativa. No se crean tareas, subtareas ni comentarios remotos. init --jira-issue <clave-o-url> sólo conserva una referencia local opcional.

En CI/CD o terminales no interactivas no se solicitan datos: el comportamiento se mantiene determinista y usa el fallback local.

Usa confirmaciones explícitas antes de ejecutar --cutover, modificar versiones, generar documentación o lanzar análisis.

Desarrollo

npm install
npm run lint
npm test

Los tests cubren integración de Jira, extracción y ejecución de endpoints, paridad PRE/POST, resumen maestro, versionado, generación de README, workflow Markdown para IDEs IA, calidad JaCoCo/SonarQube y wizard.

Para probar el empaquetado antes de publicar:

npm pack --dry-run

Seguridad

• Los comandos de endpoints ejecutan sólo GET.
• init gestiona un bloque idempotente de .gitignore para evitar subir secretos, evidencias y workflows locales.
• Jira no requiere credenciales ni conexiones desde el CLI. Los tokens OAuth2 y SonarQube se usan únicamente para sus operaciones correspondientes y no se guardan en reportes.
• No incluyas .env, credenciales, archivos de evidencia o artefactos de calidad en el repositorio.
• Revisa los cambios de version y readme antes de subirlos a la rama del microservicio.
• Usa secretos de CI/CD o un gestor de secretos para las credenciales de producción.

Licencia

MIT.