From 524c00c34ca1942119b071814bf8e57fbf851e47 Mon Sep 17 00:00:00 2001 From: GedMarcEE Date: Thu, 12 Nov 2026 11:10:07 +0200 Subject: [PATCH] Add Spring to Quarkus migration skill and HTTP verification --- .apm/skills/spring-to-quarkus/SKILL.md | 20 ++++++++++++ .../spring-to-quarkus/agents/openai.yaml | 4 +++ .../spring-to-quarkus/references/migration.md | 32 +++++++++++++++++++ .../references/provenance.md | 11 +++++++ .../references/verification.md | 16 ++++++++++ .github/workflows/validate.yml | 16 ++++++++++ marketplace.json | 6 ++++ tests/fixtures/spring-to-quarkus/pom.xml | 7 ++++ .../main/java/example/GreetingResource.java | 20 ++++++++++++ .../main/java/example/GreetingService.java | 8 +++++ .../src/test/java/example/MigrationTest.java | 20 ++++++++++++ 11 files changed, 160 insertions(+) create mode 100644 .apm/skills/spring-to-quarkus/SKILL.md create mode 100644 .apm/skills/spring-to-quarkus/agents/openai.yaml create mode 100644 .apm/skills/spring-to-quarkus/references/migration.md create mode 100644 .apm/skills/spring-to-quarkus/references/provenance.md create mode 100644 .apm/skills/spring-to-quarkus/references/verification.md create mode 100644 tests/fixtures/spring-to-quarkus/pom.xml create mode 100644 tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingResource.java create mode 100644 tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingService.java create mode 100644 tests/fixtures/spring-to-quarkus/src/test/java/example/MigrationTest.java diff --git a/.apm/skills/spring-to-quarkus/SKILL.md b/.apm/skills/spring-to-quarkus/SKILL.md new file mode 100644 index 0000000..8ddb386 --- /dev/null +++ b/.apm/skills/spring-to-quarkus/SKILL.md @@ -0,0 +1,20 @@ +--- +name: spring-to-quarkus +description: Assess, implement or review migration of a Spring or Spring Boot application to Quarkus, choosing native Quarkus APIs or documented Spring compatibility extensions and verifying HTTP, injection, configuration, security and persistence contracts. Use for framework replacement, not a Spring Boot version upgrade. +--- + +# Spring to Quarkus + +Read [provenance and evidence boundaries](references/provenance.md). Inventory the source Spring/Boot version, JDK, language, build, MVC or WebFlux stack, bean lifecycle, configuration, security, data access, transactions, messaging and deployment. Establish observable contracts and a passing baseline before edits; preserve unrelated work. + +Choose the destination with [migration decisions](references/migration.md): native CDI and Jakarta REST, or explicitly supported Spring annotation compatibility. Record unsupported features and a replacement for each. Do not assume that a Spring library works because its annotations compile, or infer Boot 4 compatibility from Boot 3 examples. + +Resolve a compatible Quarkus platform, plugin and Java baseline from the selected release documentation. Replace Boot packaging and starters with selected Quarkus extensions. Preserve approved dependency sources and inspect the effective build and dependency tree. + +Migrate one vertical slice through startup, constructor injection, configuration, HTTP binding, serialization and tests. Verify clean build-time augmentation and actual HTTP behaviour before expanding. Keep blocking persistence and network calls off event-loop threads; explicitly preserve cancellation and context when adapting Reactor to Mutiny. + +Port security and integrations with negative-path tests. Preserve authorization, CSRF, TLS, transaction boundaries and database contracts. Do not widen access, enable destructive schema generation or silently start external test services to make tests pass. + +Run [acceptance checks](references/verification.md). Remove obsolete Spring runtime and build components only after retained APIs have documented compatibility extensions or tested replacements. Review packaged execution separately from development mode; native-image support needs its own evidence. + +Report the chosen strategy, pinned versions, unsupported features, changed contracts and commands with test counts, failures and skips. Distinguish local checks, CI and deployment. Upstream tools and this skill do not authorize commits, pull requests or production changes beyond the user's requested scope. diff --git a/.apm/skills/spring-to-quarkus/agents/openai.yaml b/.apm/skills/spring-to-quarkus/agents/openai.yaml new file mode 100644 index 0000000..23fdf61 --- /dev/null +++ b/.apm/skills/spring-to-quarkus/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Spring to Quarkus" + short_description: "Migrate Spring applications to verified Quarkus contracts" + default_prompt: "Use $spring-to-quarkus to assess this Spring application, choose a Quarkus migration strategy, and implement and verify a vertical slice." diff --git a/.apm/skills/spring-to-quarkus/references/migration.md b/.apm/skills/spring-to-quarkus/references/migration.md new file mode 100644 index 0000000..62f024f --- /dev/null +++ b/.apm/skills/spring-to-quarkus/references/migration.md @@ -0,0 +1,32 @@ +# Migration decisions + +## Destination and upstream guidance + +The [official migration overview](https://quarkus.io/spring/migrate/) describes native Quarkus and Spring compatibility destinations and links the [Quarkus agent skills](https://github.com/quarkusio/skills). Consult that maintained guidance when useful; review its source and current revision before installing or running it. This package does not install it automatically or copy its instructions. Tool-generated edits still require contract review. + +Prefer native APIs when the intended result removes Spring dependencies. Compatibility can reduce changes where every retained annotation and API is documented for the chosen Quarkus version. Record that choice per module, including any temporary compatibility dependency and its removal criteria. + +| Spring concern | Quarkus migration decision and verification | +| --- | --- | +| Boot parent, starters, launcher | Import a compatible platform BOM and matching Quarkus build plugin; choose extensions and packaging deliberately. Verify effective dependencies and packaged startup. | +| Bean configuration, injection, scopes | Map to CDI beans, qualifiers and producers; check discovery, scope, proxying, conditional beans and initialization order. Review reflection and dynamically registered beans against build-time discovery. | +| Spring DI compatibility | The extension interprets supported metadata without starting a Spring application context. ApplicationContext calls, BeanPostProcessors and arbitrary Spring infrastructure need replacements. | +| MVC controllers | Use Jakarta REST resources and the selected JSON extension, or supported Spring Web annotations with the required REST implementation. Verify binding, validation, exception mapping, content negotiation, status codes and error bodies. Servlet-specific filters and APIs need a separately justified stack. | +| WebFlux and Reactor | Decide threading and streaming contracts before adapting types. Preserve cancellation, backpressure and security context; verify blocking isolation. A synchronous return type does not prove reactive equivalence. | +| Properties and profiles | Map keys explicitly to Quarkus configuration and config mappings. Distinguish build-time settings from runtime overrides, including profile precedence and missing required values. | +| JPA and repositories | Choose Hibernate ORM/Panache or the documented Spring Data JPA subset. Inventory derived queries, custom repositories, pagination, projections and locking rather than assuming API coverage. Preserve identifiers and schema migrations. | +| Transactions | Map propagation, rollback rules and resource enlistment explicitly. Reactive persistence is a separate execution model, not a mechanical repository replacement. Test rollback and lazy access boundaries. | +| Security | Replace authentication providers and filter-chain behaviour explicitly. The Spring Security extension supports a subset of authorization annotations/expressions; it is not the Spring Security runtime. Verify role prefix semantics, method interception, OIDC/JWT, CSRF, CORS, sessions and tenant isolation as applicable. | +| Events, scheduling and messaging | Distinguish in-process events from durable messaging. Preserve acknowledgement, retry, ordering, scheduling concurrency and shutdown behaviour; do not replace delivery guarantees with local callbacks. | +| Actuator and operations | Map required health, metrics, tracing and management endpoints with equivalent exposure controls. Validate shutdown and readiness in the packaged application. | + +## Version-specific sources + +Read only the guides relevant to the inventory, using documentation matching the selected release: + +- [CDI reference](https://quarkus.io/guides/cdi-reference) and [Spring DI](https://quarkus.io/guides/spring-di/): bean discovery and supported compatibility metadata. +- [REST](https://quarkus.io/guides/rest) and [Spring Web](https://quarkus.io/guides/spring-web/): HTTP bindings and execution model. +- [Configuration reference](https://quarkus.io/guides/config-reference): build/runtime settings and profiles. +- [Spring Data JPA](https://quarkus.io/guides/spring-data-jpa/) and [transactions](https://quarkus.io/guides/transaction): repository support and transaction semantics. +- [Spring Security](https://quarkus.io/guides/spring-security/) and [security overview](https://quarkus.io/guides/security-overview): supported authorization and authentication choices. +- [Testing](https://quarkus.io/guides/getting-started-testing): application and packaged integration test boundaries. diff --git a/.apm/skills/spring-to-quarkus/references/provenance.md b/.apm/skills/spring-to-quarkus/references/provenance.md new file mode 100644 index 0000000..3264156 --- /dev/null +++ b/.apm/skills/spring-to-quarkus/references/provenance.md @@ -0,0 +1,11 @@ +# Provenance and scope + +Independently authored for this marketplace on 2026-11-12 from official Quarkus documentation linked in [migration decisions](migration.md). The official migration overview links `quarkusio/skills`; this package references that upstream resource rather than copying or installing it. No upstream skill or vendor example source is redistributed. This is not a vendor-endorsed package. + +Experimental; long-term named ownership remains unassigned. Requires consuming application source, compatible JDK/build tools, dependency access and approved test services. No MCP server or other installed skill is required. Cross-harness compatibility is not established. + +The bounded fixture baseline pins Spring Boot 3.5.16 and Quarkus 3.40.1 on Java 17-compatible source. These versions are test evidence, not a universal target or a claim of latest-release coverage. CI runs both HTTP fixtures on Java 17. The pull request records actual local and hosted outcomes separately. + +Structural validation, content audits and repository security scanners are distinct from behavioural migration tests. Python dependency auditing does not certify JVM dependencies or the security of a migrated application. Compatibility extensions, Boot 4 migration, Kotlin/Gradle, persistence, authentication, messaging, performance, native images and deployment remain outside this fixture's evidence. + +Local verification on 2026-11-12: Maven 4.0.0-rc-7 / Java 25 ran both fixtures successfully, one real-HTTP test each with zero failures, errors or skips. The Quarkus package build also passed. This does not establish packaged process or native-image execution. diff --git a/.apm/skills/spring-to-quarkus/references/verification.md b/.apm/skills/spring-to-quarkus/references/verification.md new file mode 100644 index 0000000..fa375ba --- /dev/null +++ b/.apm/skills/spring-to-quarkus/references/verification.md @@ -0,0 +1,16 @@ +# Acceptance evidence + +Compare the same external contracts before and after migration. Use isolated, approved test services and explicit timeouts; inspect test counts and skipped tests. + +| Area | Required evidence when applicable | +| --- | --- | +| Build and startup | Clean augmentation, resolved BOM/plugin versions, discovered beans, required configuration errors and packaged process startup. | +| HTTP | Real requests for successful JSON, absent routes, invalid inputs, exception bodies, methods, content types, dates, decimals and nulls. | +| Injection/configuration | Constructor dependencies, qualifiers, scopes, conditional components, profile precedence and runtime overrides. | +| Security | Anonymous, expired credentials, insufficient roles, allowed users and cross-tenant denials; management endpoint exposure and browser protections. | +| Data | Representative repository queries, pagination, transaction commit/rollback, schema compatibility and concurrency. | +| Reactive/integrations | Event-loop isolation, cancellation, streaming/backpressure, messaging retries/acknowledgement and context propagation. | +| Operations | Readiness/liveness, shutdown, metrics/tracing, deployment configuration and rollback procedure. | +| Removal | Dependency tree and source search identify remaining Spring APIs and their intentional compatibility providers; no obsolete Boot launcher. | + +Repository smoke fixtures compare the existing Spring baseline at `tests/fixtures/spring-to-micronaut-baseline` with `tests/fixtures/spring-to-quarkus`. Both exercise constructor injection and real HTTP: JSON success, content type and missing-route status. The new target uses native CDI and Jakarta REST, not Spring compatibility. These checks do not establish security, persistence, reactive, compatibility-extension, native-image or production acceptance. An application migration needs the broader scenarios above. diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 38aef06..256611c 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -74,6 +74,22 @@ jobs: run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut-baseline/pom.xml verify - name: Verify native Micronaut fixture run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut/pom.xml verify + spring-quarkus-smoke: + name: Spring to Quarkus native HTTP contract + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5 + with: + distribution: temurin + java-version: '17' + - name: Verify Spring HTTP baseline + run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut-baseline/pom.xml verify + - name: Verify native Quarkus HTTP target + run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-quarkus/pom.xml verify vertx-smoke: name: Quarkus to Vert.x HTTP and event-bus smoke runs-on: ubuntu-latest diff --git a/marketplace.json b/marketplace.json index a99c196..a87f65b 100644 --- a/marketplace.json +++ b/marketplace.json @@ -100,6 +100,12 @@ "description": "Migrate Quarkus services to Kotlin http4k handlers. Experimental guidance.", "category": "Migration", "source": "./.apm/skills/quarkus-to-http4k" + }, + { + "name": "spring-to-quarkus", + "description": "Experimental Spring-to-Quarkus migration with native and compatibility strategy assessment and HTTP verification.", + "category": "Migration", + "source": "./.apm/skills/spring-to-quarkus" } ] } diff --git a/tests/fixtures/spring-to-quarkus/pom.xml b/tests/fixtures/spring-to-quarkus/pom.xml new file mode 100644 index 0000000..a473e56 --- /dev/null +++ b/tests/fixtures/spring-to-quarkus/pom.xml @@ -0,0 +1,7 @@ + +4.0.0examplespring-to-quarkus-smoke1.0 +17UTF-83.40.1 +io.quarkus.platformquarkus-bom${quarkus.version}pomimport +io.quarkusquarkus-rest-jacksonio.quarkusquarkus-junit5test +io.quarkus.platformquarkus-maven-plugin${quarkus.version}truebuildgenerate-codegenerate-code-testsorg.apache.maven.pluginsmaven-compiler-plugin3.14.1trueorg.apache.maven.pluginsmaven-surefire-plugin3.5.4trueorg.jboss.logmanager.LogManager0 + diff --git a/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingResource.java b/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingResource.java new file mode 100644 index 0000000..c64cc16 --- /dev/null +++ b/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingResource.java @@ -0,0 +1,20 @@ +package example; + +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; +import java.util.Map; + +@Path("/hello") +public class GreetingResource { + private final GreetingService service; + + @Inject + public GreetingResource(GreetingService service) { this.service = service; } + + @GET + @Produces(MediaType.APPLICATION_JSON) + public Map hello() { return Map.of("message", service.greeting()); } +} diff --git a/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingService.java b/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingService.java new file mode 100644 index 0000000..4db2856 --- /dev/null +++ b/tests/fixtures/spring-to-quarkus/src/main/java/example/GreetingService.java @@ -0,0 +1,8 @@ +package example; + +import jakarta.enterprise.context.ApplicationScoped; + +@ApplicationScoped +public class GreetingService { + public String greeting() { return "hello"; } +} diff --git a/tests/fixtures/spring-to-quarkus/src/test/java/example/MigrationTest.java b/tests/fixtures/spring-to-quarkus/src/test/java/example/MigrationTest.java new file mode 100644 index 0000000..6d45384 --- /dev/null +++ b/tests/fixtures/spring-to-quarkus/src/test/java/example/MigrationTest.java @@ -0,0 +1,20 @@ +package example; +import io.quarkus.test.junit.QuarkusTest; +import io.quarkus.test.common.http.TestHTTPResource; +import java.net.URI; +import java.net.http.*; +import org.junit.jupiter.api.Test; +import static org.junit.jupiter.api.Assertions.*; +@QuarkusTest +class MigrationTest { + @TestHTTPResource URI base; + @Test void httpContracts() throws Exception { + HttpClient client = HttpClient.newHttpClient(); + var response = client.send(HttpRequest.newBuilder(base.resolve("/hello")).timeout(java.time.Duration.ofSeconds(5)).GET().build(), HttpResponse.BodyHandlers.ofString()); + assertEquals(200, response.statusCode()); + assertEquals("{\"message\":\"hello\"}", response.body()); + assertTrue(response.headers().firstValue("content-type").orElse("").startsWith("application/json")); + var missing = client.send(HttpRequest.newBuilder(base.resolve("/missing")).timeout(java.time.Duration.ofSeconds(5)).GET().build(), HttpResponse.BodyHandlers.ofString()); + assertEquals(404, missing.statusCode()); + } +}