bmad-method-quarkus 1.0.0

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

@@ -0,0 +1,181 @@
+---
+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 exception class naming 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, defined in the **domain exception**, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short module/domain code (the BC code in DDD projects). 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.
+
+## Exception hierarchy (domain layer, framework-free)
+
+```java
+// domain/exception
+public abstract class DomainException extends RuntimeException {
+    private final String code;          // "USR-404-001"
+    private final Object[] messageArgs; // interpolated into localized message
+    protected DomainException(String code, Object... args) {
+        super(code);
+        this.code = code;
+        this.messageArgs = args;
+    }
+    public String code() { return code; }
+    public Object[] messageArgs() { return messageArgs; }
+}
+
+public final class UserNotFoundException extends DomainException {
+    public UserNotFoundException(UserId id) { super("USR-404-001", id.value()); }
+}
+```
+
+HTTP status is NOT known by the domain. The mapping code→status lives in the handler via a registry (an enum or properties-driven map in infrastructure).
+
+### Naming
+
+Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Domain exception | `<Thing><Problem>Exception`, in `domain/exception` | `UserNotFoundException`, `DuplicateEmailException` |
+| Base class | `DomainException` | |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `StaleVersionException` | |
+| Single REST handler | `GlobalExceptionHandler` (the only sanctioned `*Handler`) | |
+| gRPC counterpart | `GrpcExceptionInterceptor` | |
+| i18n components | `MessageResolver`, `ErrorCatalog` | |
+| Error DTO | `ErrorDto` | |
+| Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
+| Bundle key | the error code itself, never a prose key | `USR-404-001` |
+
+Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the domain does not know about HTTP, and 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. `UserNotFoundException` with a Spanish translation `El usuario {0} no existe.` in `errors_es.properties` is correct — `UsuarioNoEncontradoException` is not.
+
+## The single global handler (infrastructure/rest)
+
+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(DomainException 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(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.
+- Resources and use cases must NOT catch-and-format errors themselves — throw domain exceptions and let the handler translate.
+- `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.
+GEN-400-001=The request contains invalid data.
+GEN-500-001=Internal error. Contact support with the trace identifier.
+```
+
+```properties
+# errors_es.properties
+USR-404-001=El usuario {0} no existe.
+GEN-400-001=La solicitud contiene datos inválidos.
+GEN-500-001=Error interno. Contacte a soporte con el identificador de traza.
+```
+
+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. Create domain exception extending `DomainException`, named `<Thing><Problem>Exception`, with new code `<MOD>-<HTTP>-<seq>`.
+2. Register code → status/reason in `ErrorCatalog`.
+3. Add the message key to ALL locale bundles (build fails a test if a code is missing in any bundle — write that test once: iterate catalog codes × locales).
+4. Document in the error catalog page referenced by `referenceError`.

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

@@ -0,0 +1,141 @@
+---
+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 domain exceptions, 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/mapper naming conventions.
+---
+
+# 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/`. One package per service/module + major version (the module segment is the BC code in DDD projects, the service name otherwise):
+
+```protobuf
+syntax = "proto3";
+package alva.bc05.v1;
+option java_package = "com.alva.bc05.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, `infrastructure/grpc`)
+
+```java
+@GrpcService
+public class UserGrpcService implements UserService {   // Mutiny-generated interface
+
+    private final GetUserUseCase getUser;   // inbound port from application layer
+
+    public UserGrpcService(GetUserUseCase getUser) { this.getUser = getUser; }
+
+    @Override
+    public Uni<GetUserResponse> getUser(GetUserRequest req) {
+        return Uni.createFrom().item(() -> getUser.byId(new UserId(UUID.fromString(req.getUserId()))))
+            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool())  // JDBC below → worker thread
+            .map(UserGrpcMapper::toResponse);
+    }
+}
+```
+
+- gRPC service = thin adapter: map proto ↔ command/result, delegate to the use case. No business logic.
+- Blocking work (JDBC) either `@Blocking` on the method or 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` | `UserGrpcService` |
+| Client adapter | `Grpc<Port>` — port name from `application/port/out` | `GrpcCredentialsValidator` |
+| Proto ↔ domain mapper | `<Entity>GrpcMapper` | `UserGrpcMapper` |
+| Global error interceptor | `GrpcExceptionInterceptor` | |
+| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `bc05-users` |
+
+`*GrpcService` is the one place outside `application/usecase` where the `*Service` suffix is allowed — it mirrors the proto service name, which is not ours to rename. The client adapter is never called `UserServiceClient`: it implements a domain-named port, and only the `Grpc` prefix reveals 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 (domain exception → gRPC status)
+
+One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler:
+
+| Domain situation | gRPC status |
+|---|---|
+| Not found | `NOT_FOUND` |
+| Validation / bad argument | `INVALID_ARGUMENT` |
+| Business rule conflict | `FAILED_PRECONDITION` |
+| Duplicate / concurrency | `ALREADY_EXISTS` / `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 back to their own domain exceptions. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); individual services never build `StatusRuntimeException` by hand.
+
+## Client (outbound adapter)
+
+Define an outbound port in `application/port/out` (e.g., `CredentialsValidator`); the gRPC client is its adapter:
+
+```java
+@ApplicationScoped
+public class GrpcCredentialsValidator implements CredentialsValidator {
+
+    @GrpcClient("bc05-users") UserService client;   // Mutiny stub
+
+    @Override
+    public boolean validate(Credentials c) {
+        return client.validateCredentials(toRequest(c))
+            .map(ValidateCredentialsResponse::getValid)
+            .await().atMost(Duration.ofSeconds(2));
+    }
+}
+```
+
+```properties
+quarkus.grpc.clients.bc05-users.host=bc05-users.internal
+quarkus.grpc.clients.bc05-users.port=9000
+quarkus.grpc.clients.bc05-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` back into the caller's domain exceptions at the adapter — gRPC types never cross into application/domain.
+
+## 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 shared contracts module, package `vN`, dedicated Request/Response.
+2. Server adapter delegating to a use case; blocking handled explicitly.
+3. Client behind an outbound port, deadline configured.
+4. Error mapping covered by the global interceptor (add new code if needed).
+5. Contract check in CI (buf breaking-change detection or equivalent).