bmad-method-quarkus 1.0.3 → 1.0.4

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-error-handling-i18n/SKILL.md

@@ -1,215 +0,0 @@
----
-name: quarkus-error-handling-i18n
-description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines the single BusinessException type (code + args, never a pre-rendered message), the ErrorCatalog/MessageResolver machinery in common/, and the English-identifiers/localized-messages rule.
----
-
-# Unified Exception Handler + i18n Responses (Quarkus, TMF-aligned)
-
-One handler, one error contract, localized messages resolved from the `Accept-Language` header. No endpoint ever builds its own error response.
-
-Applies to any Quarkus backend project. Defaults below (locale set, error-code format) are overridable by project directives (CLAUDE.md, ADRs, explicit instructions) — the single-handler and stable-code principles are the part to defend.
-
-## Error contract (TM Forum TMF630 Error schema)
-
-All error responses use `application/json` with the TMF Error structure (interoperable with TMF Open APIs; if the project is not TMF-facing, RFC 9457 `application/problem+json` is the fallback — same handler, different DTO):
-
-```json
-{
-  "code": "USR-404-001",
-  "reason": "Not Found",
-  "message": "User 8f14e45f does not exist.",
-  "status": "404",
-  "referenceError": "https://docs.company.com/errors/USR-404-001",
-  "@type": "Error"
-}
-```
-
-- `code`: stable, machine-readable, carried by the thrown `BusinessException`, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short uppercase code derived from the semantic module name or its main entity (`IAM`, `USR`, `PTY` — never a `bcNN` inventory code; see quarkus-hexagonal-core skill). It is also the **bundle key**. Never reworded, never localized.
-- `message`: human-readable, **localized** via bundles.
-- `referenceError`: link to error catalog docs.
-- Add `traceId` propagation via response header `X-Trace-Id` (see observability skill), not in the body.
-
-## One business exception (`common/exception`)
-
-The vertical-slice standard uses a **single** business exception carrying a stable code plus interpolation arguments — not a subclass per error. The subclass hierarchy bought nothing that the code does not already express, and cost one file per error:
-
-```java
-// common/exception
-public class BusinessException extends RuntimeException {
-    private final String code;          // "USR-404-001"
-    private final Object[] messageArgs; // interpolated into the localized message
-    public BusinessException(String code, Object... args) {
-        super(code);                    // super message = the code; the human text is resolved at the edge
-        this.code = code;
-        this.messageArgs = args;
-    }
-    public BusinessException(String code, Throwable cause, Object... args) { ... }
-    public String code() { return code; }
-    public Object[] messageArgs() { return messageArgs; }
-}
-```
-
-Thrown from the slice `Handler` and nowhere else:
-
-```java
-throw new BusinessException("USR-404-001", userId);
-```
-
-**The thrower never formats or translates the message.** A `Handler` that injects a `ResourceBundle` and passes a rendered string silently pins every response to one language, defeating `Accept-Language`. Resolution happens once, at the edge, in `GlobalExceptionHandler` / `GrpcExceptionInterceptor`.
-
-HTTP status is not known by the `Handler` either. The mapping code→status lives in `ErrorCatalog` (`common/error`).
-
-One sibling, not a subclass: `StaleVersionException` (optimistic-lock conflict) is the only other code-carrying exception. It is NOT a `BusinessException` subtype and NOT part of the `PersistenceException` family — a version conflict is a client-actionable 409, not an infrastructure failure hidden behind a 500. It is thrown by the `Handler` when a versioned `UPDATE` returns 0 rows (never by `SqlStateTranslator` — there is no `SQLException` involved) and mapped by its own dedicated mapper below.
-
-### Naming
-
-Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| Business exception | `BusinessException` — one class, in `common/exception` | thrown with `("USR-404-001", id)` |
-| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, in `common/exception` | |
-| Concurrency-conflict exception | `StaleVersionException` — standalone, code-carrying (`code + args`, like `BusinessException`), in `common/exception` | thrown with `("PTY-409-001", id)` |
-| SQLState translator | `SqlStateTranslator`, in `common/error` | |
-| Single REST handler | `GlobalExceptionHandler`, in `common/error` | |
-| gRPC counterpart | `GrpcExceptionInterceptor`, in `common/error` | |
-| i18n components | `MessageResolver`, `ErrorCatalog` | |
-| Error DTO | `ErrorDto` (TMF630 Error shape) | |
-| Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
-| Bundle key | the error code itself, never a prose key | `USR-404-001` |
-
-`GlobalExceptionHandler` is no longer "the only sanctioned `*Handler`" — under the slice standard `*Handler` is the business-logic class of every slice (`CreatePartyIndividualHandler`). What stays true is that there is exactly **one** global exception handler per transport, both in `common/error`, and that no `Resource`, `GrpcService` or `Consumer` builds an error response itself.
-
-Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
-
-**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. A slice named `create_party_individual` throwing `PTY-400-001`, translated as `El campo ''{0}'' es obligatorio.` in `errors_es.properties`, is correct — a class or key named `crear_persona.campo_obligatorio` is not.
-
-## The single global handler (`common/error`)
-
-Exactly ONE class. Use `@ServerExceptionMapper` (Quarkus REST) — build-time wired, native-friendly:
-
-```java
-@ApplicationScoped   // required for constructor injection into the mapper class
-public class GlobalExceptionHandler {
-
-    private final MessageResolver messages;   // i18n component below
-    private final ErrorCatalog catalog;       // code -> HTTP status + reason
-
-    public GlobalExceptionHandler(MessageResolver messages, ErrorCatalog catalog) {
-        this.messages = messages;
-        this.catalog = catalog;
-    }
-
-    @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(BusinessException e, HttpHeaders headers) {
-        var status = catalog.statusOf(e.code());               // e.g. 404
-        var msg = messages.resolve(e.code(), headers, e.messageArgs());
-        return RestResponse.status(status,
-            ErrorDto.of(e.code(), status, msg));
-    }
-
-    @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(StaleVersionException e, HttpHeaders headers) {
-        // optimistic-lock conflict: 409 per catalog, client-visible and localized like a business error
-        var status = catalog.statusOf(e.code());               // 409
-        var msg = messages.resolve(e.code(), headers, e.messageArgs());
-        return RestResponse.status(status, ErrorDto.of(e.code(), status, msg));
-    }
-
-    @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(PersistenceException e, HttpHeaders headers) {
-        // technical failures: 500/503 per catalog, stack trace to logs only
-        ...
-    }
-
-    @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(ConstraintViolationException e, HttpHeaders headers) {
-        // 400, code "GEN-400-001", join violations into localized detail
-        ...
-    }
-
-    @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(Exception e, HttpHeaders headers) {
-        Log.error("Unhandled exception", e);                   // full stack only in logs
-        var msg = messages.resolve("GEN-500-001", headers);
-        return RestResponse.status(500, ErrorDto.of("GEN-500-001", 500, msg));
-    }
-}
-```
-
-Rules:
-- Catch-all `Exception` mapper is mandatory: internal details/stack traces NEVER reach the client. Log with full context (trace_id lands in the log automatically via MDC).
-- Validation errors (Bean Validation) map to 400 with one generic code + per-field details array.
-- `Resource`, `GrpcService`, `Consumer` and `Handler` classes must NOT catch-and-format errors themselves — throw `BusinessException` with a code and let the handler translate. A `try { ... } catch (BusinessException e) { return Response.status(400)... }` inside a `Resource` is the anti-pattern this skill exists to prevent: it bypasses the catalog, the locale and the trace header.
-- `ErrorDto` is `@RegisterForReflection` (native).
-
-## i18n resolution from Accept-Language
-
-### Configuration
-
-```properties
-quarkus.locales=en,es,pt
-quarkus.default-locale=en
-```
-
-`quarkus.locales` also tells the native image which locale data to embed — required for native builds.
-
-### Message bundles
-
-`src/main/resources/messages/errors.properties` (default = **en**), `errors_es.properties`, `errors_pt.properties`:
-
-```properties
-# errors.properties (en, default)
-USR-404-001=User {0} does not exist.
-PTY-400-001=The ''{0}'' field is required.
-GEN-400-001=The request contains invalid data.
-GEN-500-001=Internal error. Contact support with the trace identifier.
-```
-
-Bundles are **per application, keyed by error code** — not per slice, not keyed by prose. A slice contributes rows to the same files, which is what keeps "every code exists in every locale" a single testable invariant. (`''` escapes a literal apostrophe for `MessageFormat`.)
-
-```properties
-# errors_es.properties
-USR-404-001=El usuario {0} no existe.
-PTY-400-001=El campo ''{0}'' es obligatorio.
-GEN-400-001=La solicitud contiene datos inválidos.
-GEN-500-001=Error interno. Contacte a soporte con el identificador de traza.
-```
-
-Quality bar per language — Spanish: formal or infinitive, precise, no vague `Error de validación`. English: direct declarative, no vague `something went wrong`. Same key order in every file so diffs stay readable.
-
-For native: `quarkus.native.resources.includes=messages/*.properties`.
-
-### Resolver
-
-```java
-@ApplicationScoped
-public class MessageResolver {
-    public String resolve(String code, HttpHeaders headers, Object... args) {
-        var locale = headers.getAcceptableLanguages().stream()
-            .findFirst().filter(l -> !"*".equals(l.getLanguage()))
-            .orElse(Locale.ENGLISH);   // default locale = en
-        var bundle = ResourceBundle.getBundle("messages.errors", locale);
-        var pattern = bundle.containsKey(code) ? bundle.getString(code)
-                                               : bundle.getString("GEN-500-001");
-        return MessageFormat.format(pattern, args);
-    }
-}
-```
-
-`getAcceptableLanguages()` already returns the header parsed and sorted by q-value — take the first supported one. Unknown locales fall back to the default silently (never 406 for language).
-
-Alternative: `quarkus-messages` / SmallRye localized message bundles (`@MessageBundle`) give compile-time checked bundles — prefer it in greenfield projects; the `ResourceBundle` approach above is the portable baseline.
-
-## i18n beyond errors
-
-Success-path localizable strings (notification texts, report labels) use the same resolver and bundles (`messages/app*.properties`). Data itself (entity fields) is NOT localized by this mechanism — that is a modeling concern.
-
-## Checklist when adding a new error
-
-1. Pick the next code `<MOD>-<HTTP>-<seq>` — no new exception class.
-2. Throw `new BusinessException(code, args...)` from the slice `Handler` (`validate()` or `execution()`), with the interpolation args and no rendered text.
-3. Register code → status/reason in `ErrorCatalog`.
-4. Add the message key to ALL locale bundles (a test fails the build if a code is missing in any bundle — write it once: iterate catalog codes × locales).
-5. Document in the error catalog page referenced by `referenceError`, and add the row to the slice `README.md` "Business errors" table.
-6. Assert the code (not the message) in the `HandlerTest`; assert the localized body in the `Resource` `@QuarkusTest`.

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-grpc-services/SKILL.md

@@ -1,160 +0,0 @@
----
-name: quarkus-grpc-services
-description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to BusinessException codes, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client naming conventions for the vertical-slice layout (the GrpcService lives in the slice folder and delegates to the slice Handler; outbound stubs are wrapped by capability-named beans in common/client).
----
-
-# gRPC Standard for Inter-Service Communication (Quarkus)
-
-Rule of the road: **external/north-bound = REST (TMF)**, **internal synchronous service-to-service = gRPC**, **internal asynchronous = Kafka**. If someone proposes an internal REST client, redirect to this skill. Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults.
-
-Extension: `quarkus-grpc` (fully native-compatible; code generation is build-time).
-
-## Proto conventions
-
-Location: `src/main/proto/<module>/v<major>/`, one file per capability group, published to the monorepo `contracts/` folder. One proto package per service/module + major version (the module segment is the module's semantic name — `iam`, `customer` — see quarkus-hexagonal-core skill, or the service name):
-
-```protobuf
-syntax = "proto3";
-package alva.iam.v1;
-option java_package = "com.alva.iam.grpc.v1";
-option java_multiple_files = true;
-
-service UserService {
-  rpc GetUser (GetUserRequest) returns (GetUserResponse);
-  rpc ValidateCredentials (ValidateCredentialsRequest) returns (ValidateCredentialsResponse);
-}
-
-message GetUserRequest { string user_id = 1; }
-message GetUserResponse { User user = 1; }
-```
-
-Rules:
-- Package version `v1`, `v2` — breaking change = new package version, run both during migration.
-- `snake_case` fields, `PascalCase` messages/services, one `XxxRequest`/`XxxResponse` pair per RPC (never reuse messages across RPCs — they evolve independently).
-- Never reuse/renumber field tags; use `reserved` for removed fields.
-- Timestamps: `google.protobuf.Timestamp`; optional scalars needing presence: `optional` keyword or wrappers.
-- Proto files are contracts: keep them in a shared `contracts/` module (or a dedicated repo) consumed by both sides; do NOT copy-paste protos between services.
-- Streaming RPCs only with a justified use case (bulk export, watch); default is unary.
-
-## Server (inbound adapter, in the slice folder)
-
-```java
-@GrpcService
-public class UserGrpcService implements UserService {   // Mutiny-generated interface
-
-    @Inject FindUserHandler findUser;      // the slice's Handler, blocking
-
-    @Override
-    public Uni<GetUserResponse> getUser(GetUserRequest req) {
-        return Uni.createFrom().item(() -> {
-                var request = FindUserRequestDto.builder().userId(req.getUserId()).build();
-                var result = findUser.process(request);           // blocking JDBC
-                return GetUserResponse.newBuilder()
-                    .setUser(User.newBuilder().setId(result.getId()).setEmail(result.getEmail()))
-                    .build();
-            })
-            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool());  // JDBC → worker thread
-    }
-}
-```
-
-- gRPC service = thin adapter: convert proto ↔ DTO, delegate to the slice `Handler`. No business logic, no JDBC, no `Connection`.
-- **Proto ↔ DTO conversion happens inline, inside the `item(() -> ...)` lambda.** There is no `*GrpcMapper` class — `*Mapper` is a banned suffix (see quarkus-hexagonal-core skill).
-- This class and the integration beans in `common/client` are the **only** two places Mutiny is allowed; the ArchUnit rule `reactiveIsQuarantined` enforces it. Never let `Uni`/`Multi` reach a `Handler` or `Sql`.
-- Blocking work (JDBC) either `@Blocking` on the method or the explicit worker pool as above.
-
-### Naming
-
-Canonical rules in the quarkus-hexagonal-core skill; gRPC specifics:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| Proto service | `<Entity>Service` (PascalCase) | `UserService` |
-| Proto RPC | `<Verb><Entity>` | `GetUser`, `ValidateCredentials` |
-| Proto messages | `<Rpc>Request` / `<Rpc>Response`, one pair per RPC | `GetUserRequest` |
-| Proto fields | `snake_case` | `user_id` |
-| Server adapter | `<ProtoService>GrpcService`, in the slice folder | `UserGrpcService` |
-| Outbound integration bean | capability noun, **no technology**, in `common/client` | `CredentialsValidator` |
-| Global error interceptor | `GrpcExceptionInterceptor`, in `common/error` | |
-| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `iam-users` |
-
-`*GrpcService` is the **only** class allowed to end in `Service` under the slice standard — it mirrors the proto service name, which is not ours to rename (ArchUnit rule `serviceSuffixIsReserved`). There is no `Grpc<Port>` client adapter and no `*GrpcMapper`: the outbound bean is named after the capability it provides, and only its internals reveal that gRPC is the transport.
-
-Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
-
-## Error mapping (`BusinessException` → gRPC status)
-
-One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler. The status is derived from the code's entry in `ErrorCatalog`, not from the exception class:
-
-| Situation (per `ErrorCatalog`) | gRPC status |
-|---|---|
-| Not found | `NOT_FOUND` |
-| Validation / bad argument | `INVALID_ARGUMENT` |
-| Business rule conflict | `FAILED_PRECONDITION` |
-| Duplicate | `ALREADY_EXISTS` |
-| Stale version / concurrency (`StaleVersionException`) | `ABORTED` |
-| Auth | `UNAUTHENTICATED` / `PERMISSION_DENIED` |
-| Anything unexpected | `INTERNAL` (no details leaked) |
-
-Attach the stable error code in trailers metadata key `error-code` so callers can map it back through their own `ErrorCatalog`. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor` in `common/error`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); it resolves the localized message the same way, from the request's locale metadata. Individual services never build `StatusRuntimeException` by hand, and no `GrpcService` catches `BusinessException`.
-
-## Client (outbound integration bean, `common/client`)
-
-A slice `Handler` must never hold a `@GrpcClient` stub: the generated stub returns `Uni`, which would drag Mutiny into the business logic and break the `reactiveIsQuarantined` rule. Wrap it in a capability-named bean that `await()`s internally and exposes plain types:
-
-```java
-// common/client — named for what it provides, not for how
-@ApplicationScoped
-public class CredentialsValidator {
-
-    @GrpcClient("iam-users") UserService client;   // Mutiny stub, contained here
-
-    public boolean validate(String username, String password) {
-        return client.validateCredentials(
-                ValidateCredentialsRequest.newBuilder()
-                    .setUsername(username).setPassword(password).build())
-            .map(ValidateCredentialsResponse::getValid)
-            .await().atMost(Duration.ofSeconds(2));   // deadline also set in config
-    }
-}
-```
-
-The `Handler` then injects it like any other collaborator:
-
-```java
-@Inject CredentialsValidator credentials;   // returns boolean, knows nothing about gRPC
-```
-
-The bean always lives in `common/client`, even when only one slice calls it today — that is the package the `reactiveIsQuarantined` ArchUnit rule exempts (see quarkus-hexagonal-core skill), and it saves relocating the bean the day a second slice needs it. It is mocked in `HandlerTest` exactly like the `Sql` class.
-
-An interface is warranted only under the core skill's "when to add an interface back" rule — a second real implementation, a cross-module boundary, or a `common/` consumer that must not see the slice.
-
-```properties
-quarkus.grpc.clients.iam-users.host=iam-users.internal
-quarkus.grpc.clients.iam-users.port=9000
-quarkus.grpc.clients.iam-users.deadline=2s
-```
-
-Rules:
-- **Deadline on every client** (config `deadline` or per-call). No unbounded internal calls, ever — cascading hangs kill native pods just as well.
-- Retries only for idempotent RPCs and only `UNAVAILABLE`/`DEADLINE_EXCEEDED`, with budget — prefer platform/mesh retry policy over hand-rolled loops.
-- TLS/mTLS per platform standard (`quarkus.grpc.clients.*.ssl.*` / mesh-provided).
-- Translate `StatusRuntimeException` into a `BusinessException` carrying the caller's own error code, inside the integration bean — gRPC types (and `Uni`) never reach a `Handler`. Read the upstream code from the `error-code` trailer and map it through the caller's `ErrorCatalog`.
-
-## Health & reflection
-
-- `quarkus-smallrye-health` + gRPC health service enabled (`quarkus.grpc.server.health.enabled=true`) → Kubernetes gRPC probes.
-- Server reflection (`quarkus.grpc.server.enable-reflection-service=true`) in **dev/test only** (grpcurl debugging); off in prod, same policy as Swagger UI.
-
-## Observability
-
-Tracing is automatic when `quarkus-opentelemetry` is present — `traceparent` propagates via gRPC metadata on both server and client. No manual work; see quarkus-observability-otel skill.
-
-## Checklist for a new RPC
-
-1. Proto in `src/main/proto/<module>/v<major>/`, published to `contracts/`, dedicated Request/Response pair.
-2. `<ProtoService>GrpcService` in the slice folder delegating to the slice `Handler`; proto ↔ DTO conversion inline; blocking handled by `runSubscriptionOn` or `@Blocking`.
-3. Outbound calls wrapped in a capability-named bean in `common/client` that `await()`s and returns plain types; deadline configured.
-4. Error mapping covered by the global interceptor (register any new code in `ErrorCatalog` + all locale bundles).
-5. Contract check in CI (buf breaking-change detection or equivalent).
-6. No `Uni` outside the `GrpcService` and the integration bean — `reactiveIsQuarantined` proves it.