feat: Add addSpec() builder method for multi-spec servers

Introduces two addSpec() overloads on OpenApiServer.Builder: one accepting
a Spec, handler map, and security-validator map, and one convenience form
with no validators. The build() method is rewritten to either consume the
bindings list (addSpec path) or synthesise a single binding from the legacy
spec()/handlers()/securityValidator() fields. Mixing the two forms throws
IllegalStateException. Cross-binding duplicate-basePath detection added.

Author: thced

docs/superpowers/plans/2026-05-22-multiple-specs.md

@@ -321,7 +321,7 @@ Committed as: `abe2369` (Google Java Formatter reformatted javadoc wrapping; pre
 **Files:**
 - Create: `src/test/java/com/retailsvc/http/MultiSpecServerTest.java`
 
-- [ ] **Step 1: Write the failing test**
+- [x] **Step 1: Write the failing test**
 
 ```java
 package com.retailsvc.http;
@@ -383,12 +383,12 @@ class MultiSpecServerTest {
 
 Note: the test uses `useExternalAuthentication()` to side-step per-spec validator wiring — the security branch is covered separately in Task 8. It uses the existing `/ping` operation from `openapi.json` (which is GET-only and unsecured per the fixture). If the fixture's `/ping` requires auth, switch to the first GET-only unsecured operation in the spec — discoverable by inspecting `src/test/resources/openapi.json`.
 
-- [ ] **Step 2: Run the test to verify it fails**
+- [x] **Step 2: Run the test to verify it fails**
 
 Run: `mvn -q test -Dtest=MultiSpecServerTest#servesTwoBindingsOnDistinctBasePaths`
 Expected: COMPILE FAILURE — `addSpec` does not yet exist on `Builder`.
 
-- [ ] **Step 3: Do NOT commit yet** — proceed to Task 5 to make it pass.
+- [x] **Step 3: Do NOT commit yet** — proceed to Task 5 to make it pass.
 
 ---
 
@@ -397,7 +397,7 @@ Expected: COMPILE FAILURE — `addSpec` does not yet exist on `Builder`.
 **Files:**
 - Modify: `src/main/java/com/retailsvc/http/OpenApiServer.java`
 
-- [ ] **Step 1: Add bindings list and `addSpec` methods to `Builder`**
+- [x] **Step 1: Add bindings list and `addSpec` methods to `Builder`**
 
 Inside `Builder`, alongside the existing fields, add:
 
@@ -427,7 +427,7 @@ public Builder addSpec(Spec spec, Map<String, RequestHandler> handlers) {
 }
 ```
 
-- [ ] **Step 2: Update `build()` to consume bindings**
+- [x] **Step 2: Update `build()` to consume bindings**
 
 Replace the `build()` method body so it either:
 - uses the explicit `bindings` list when `addSpec()` was called, OR
@@ -510,17 +510,17 @@ public OpenApiServer build() throws IOException {
 }
 ```
 
-- [ ] **Step 3: Run the new test**
+- [x] **Step 3: Run the new test**
 
 Run: `mvn -q test -Dtest=MultiSpecServerTest#servesTwoBindingsOnDistinctBasePaths`
 Expected: PASS.
 
-- [ ] **Step 4: Run the full suite to confirm nothing regressed**
+- [x] **Step 4: Run the full suite to confirm nothing regressed**
 
 Run: `mvn -q test`
 Expected: BUILD SUCCESS.
 
-- [ ] **Step 5: Commit**
+- [x] **Step 5: Commit**
 
 ```bash
 git add src/main/java/com/retailsvc/http/OpenApiServer.java \

src/main/java/com/retailsvc/http/OpenApiServer.java

@@ -209,6 +209,7 @@ public static final class Builder {
     private final LinkedHashMap<String, RequestHandler> extras = new LinkedHashMap<>();
     private final Map<String, SchemeValidator> securityValidators = new LinkedHashMap<>();
     private boolean externalAuth = false;
+    private final List<SpecBinding> bindings = new ArrayList<>();
 
     private Builder() {}
 
@@ -287,6 +288,28 @@ public Builder useExternalAuthentication() {
       return this;
     }
 
+    /**
+     * Registers an OpenAPI {@link Spec} with the handlers and security validators that serve it.
+     * May be called more than once; each binding becomes its own {@link
+     * com.sun.net.httpserver.HttpContext} at the spec's {@code basePath}. {@code operationId}s and
+     * security-scheme names only need to be unique within a single spec.
+     */
+    public Builder addSpec(
+        Spec spec,
+        Map<String, RequestHandler> handlers,
+        Map<String, SchemeValidator> securityValidators) {
+      requireNonNull(spec, "spec must not be null");
+      requireNonNull(handlers, "handlers must not be null");
+      requireNonNull(securityValidators, "securityValidators must not be null");
+      bindings.add(SpecBinding.of(spec, handlers, securityValidators));
+      return this;
+    }
+
+    /** Convenience overload for specs that declare no security schemes. */
+    public Builder addSpec(Spec spec, Map<String, RequestHandler> handlers) {
+      return addSpec(spec, handlers, Map.of());
+    }
+
     public Builder exceptionHandler(ExceptionHandler exceptionHandler) {
       this.exceptionHandler = exceptionHandler;
       return this;
@@ -361,19 +384,51 @@ public Builder extraRoute(String path, RequestHandler handler) {
     }
 
     public OpenApiServer build() throws IOException {
-      requireNonNull(spec, "Spec must not be null");
-      requireNonNull(handlers, "handlers must not be null");
-      String basePath = Optional.ofNullable(spec.basePath()).orElse("/");
-      for (String path : extras.keySet()) {
-        if (path.equals(basePath)) {
+      boolean usedLegacy = spec != null || handlers != null;
+      boolean usedAddSpec = !bindings.isEmpty();
+      if (usedLegacy && usedAddSpec) {
+        throw new IllegalStateException(
+            "use either spec()/handler()/securityValidator() or addSpec(), not both");
+      }
+      List<SpecBinding> effectiveBindings;
+      if (usedAddSpec) {
+        effectiveBindings = List.copyOf(bindings);
+      } else {
+        requireNonNull(spec, "Spec must not be null");
+        requireNonNull(handlers, "handlers must not be null");
+        effectiveBindings = List.of(SpecBinding.of(spec, handlers, securityValidators));
+      }
+
+      for (SpecBinding b : effectiveBindings) {
+        if (!externalAuth) {
+          validateSecurityWiring(b.spec(), b.securityValidators());
+        }
+        validateHandlerWiring(b.spec(), b.handlers());
+      }
+
+      Map<String, String> seenBasePaths = new LinkedHashMap<>();
+      for (SpecBinding b : effectiveBindings) {
+        String bp = Optional.ofNullable(b.spec().basePath()).orElse("/");
+        String existingTitle = seenBasePaths.putIfAbsent(bp, b.spec().info().title());
+        if (existingTitle != null) {
           throw new IllegalStateException(
-              "extra handler path " + path + " conflicts with spec basePath " + basePath);
+              "duplicate basePath '"
+                  + bp
+                  + "' across specs: '"
+                  + existingTitle
+                  + "' and '"
+                  + b.spec().info().title()
+                  + "'");
         }
       }
-      if (!externalAuth) {
-        validateSecurityWiring(spec, securityValidators);
+
+      for (String path : extras.keySet()) {
+        if (seenBasePaths.containsKey(path)) {
+          throw new IllegalStateException(
+              "extra handler path " + path + " conflicts with spec basePath " + path);
+        }
       }
-      validateHandlerWiring(spec, handlers);
+
       Map<String, TypeMapper> resolved = resolveBodyMappers(bodyMappers);
       ExceptionHandler effectiveExceptionHandler =
           exceptionHandler != null ? exceptionHandler : Handlers.defaultExceptionHandler();
@@ -385,12 +440,11 @@ public OpenApiServer build() throws IOException {
               extras,
               externalAuth,
               List.copyOf(afterHooks));
-      SpecBinding binding = SpecBinding.of(spec, handlers, securityValidators);
       int resolvedPort = resolvePort();
       SSLContext sslContext =
           httpsCertChain != null ? PemSslContext.load(httpsCertChain, httpsPrivateKey) : null;
       return new OpenApiServer(
-          List.of(binding),
+          effectiveBindings,
           resolved,
           handlerConfig,
           resolvedPort,

src/test/java/com/retailsvc/http/MultiSpecServerTest.java

@@ -0,0 +1,52 @@
+package com.retailsvc.http;
+
+import static java.net.HttpURLConnection.HTTP_OK;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.retailsvc.http.spec.Spec;
+import com.retailsvc.http.support.SpecFixtures;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class MultiSpecServerTest {
+
+  @Test
+  void servesTwoBindingsOnDistinctBasePaths() throws Exception {
+    Spec v1 = SpecFixtures.specAt("http://localhost/api/v1");
+    Spec v2 = SpecFixtures.specAt("http://localhost/api/v2");
+
+    RequestHandler v1Handler = req -> Response.ok(Map.of("version", "v1"));
+    RequestHandler v2Handler = req -> Response.ok(Map.of("version", "v2"));
+
+    try (OpenApiServer server =
+        OpenApiServer.builder()
+            .port(0)
+            .addSpec(v1, handlersFor(v1, v1Handler))
+            .addSpec(v2, handlersFor(v2, v2Handler))
+            .useExternalAuthentication()
+            .build()) {
+
+      int port = server.listenPort();
+      assertThat(get("http://localhost:" + port + "/api/v1/data").statusCode()).isEqualTo(HTTP_OK);
+      assertThat(get("http://localhost:" + port + "/api/v2/data").statusCode()).isEqualTo(HTTP_OK);
+    }
+  }
+
+  private static Map<String, RequestHandler> handlersFor(Spec spec, RequestHandler shared) {
+    Map<String, RequestHandler> out = new LinkedHashMap<>();
+    spec.operations().forEach(op -> out.put(op.operationId(), shared));
+    return out;
+  }
+
+  private static HttpResponse<String> get(String url) throws Exception {
+    return HttpClient.newHttpClient()
+        .send(
+            HttpRequest.newBuilder(URI.create(url)).GET().build(),
+            HttpResponse.BodyHandlers.ofString());
+  }
+}