feat(calm-hub): Add Timeline Tools and Bug Fix Architecture Version Create (finos#2524)

* feat(calm-hub): add MCP timeline tools and fix architecture version creation

- Add TimelineTools with 6 MCP tools: listTimelines, listTimelineVersions,
  getTimeline, createTimeline, createTimelineVersion, updateTimeline
- Fix ArchitectureTools: split updateArchitecture into separate
  createArchitectureVersion (POST, ungated) and updateArchitecture (PUT,
  gated by allowPutOperations) to match the correct HTTP semantics
- Add unit tests for TimelineTools covering all tools and edge cases,
  including regression guard that createTimelineVersion works when
  allowPutOperations=false
- Extend MongoMcpIntegration and NitriteMcpIntegration with timeline
  end-to-end tests using isolated namespaces (mcp-integration/mcp-nitrite)
- Fix MongoTimelineIntegration and NitriteTimelineIntegration to capture
  the created timeline ID dynamically from the Location header instead of
  hardcoding ID 1, resolving a pre-existing test ordering fragility

Fixes finos#2522

* fix(calm-hub): address PR review feedback on MCP tools

- Fix createArchitectureVersion to resolve and preserve existing
  architecture name/description before calling the store, preventing
  null overwrites (Copilot high severity)
- Add regression test asserting name/description are preserved when
  publishing a new architecture version
- Remove dead architectureStore.createArchitectureForVersion(any()) call
  in create_architecture_version_successfully test (Copilot low severity)
- Replace brittle substring Location-header parsing in MongoTimelineIntegration
  and NitriteTimelineIntegration with Pattern.compile("/timelines/(\d+)")
  regex, matching the ID_PATTERN idiom used in MCP integration tests
- Align PatternTools.updatePattern @tool description to advertise the
  PUT-operations gate, consistent with updateArchitecture and updateTimeline
- Add three missing updateTimeline validation unit tests: invalid namespace,
  blank JSON, and non-positive timeline ID

Author: jpgough-ms

calm-hub/src/integration-test/java/integration/MongoMcpIntegration.java

@@ -19,6 +19,7 @@
 import org.finos.calm.mcp.tools.PatternTools;
 import org.finos.calm.mcp.tools.SearchTools;
 import org.finos.calm.mcp.tools.StandardTools;
+import org.finos.calm.mcp.tools.TimelineTools;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.MethodOrderer;
 import org.junit.jupiter.api.Order;
@@ -104,6 +105,7 @@ public class MongoMcpIntegration {
     private static int createdPatternId;
     private static int createdStandardId;
     private static int createdAdrId;
+    private static int createdTimelineId;
 
     @Inject
     ArchitectureTools architectureTools;
@@ -132,6 +134,9 @@ public class MongoMcpIntegration {
     @Inject
     AdrTools adrTools;
 
+    @Inject
+    TimelineTools timelineTools;
+
     private static String text(ToolResponse r) {
         return ((TextContent) r.firstContent()).text();
     }
@@ -170,6 +175,19 @@ public void setup() {
                 );
             }
 
+            if (!database.listCollectionNames().into(new ArrayList<>()).contains("timelines")) {
+                database.createCollection("timelines");
+                database.getCollection("timelines").insertOne(
+                        new Document("namespace", "finos").append("timelines", new ArrayList<>())
+                );
+            }
+
+            if (database.getCollection("timelines").countDocuments(new Document("namespace", "mcp-integration")) == 0) {
+                database.getCollection("timelines").insertOne(
+                        new Document("namespace", "mcp-integration").append("timelines", new ArrayList<>())
+                );
+            }
+
             MongoSetup.counterSetup(database);
             MongoSetup.namespaceSetup(database);
             MongoSetup.domainSetup(database);
@@ -400,7 +418,7 @@ void mcp_validation_rejects_decorator_type_filter_with_newline() {
 
     @Test
     @Order(26)
-    void mcp_update_architecture_publishes_new_version() {
+    void mcp_update_architecture_upserts_version_via_put() {
         ToolResponse result = architectureTools.updateArchitecture(
                 "finos", createdArchitectureId, "1.1.0", "{\"name\": \"mcp-test-architecture-updated\"}", null, null);
         assertThat(result.isError(), is(false));
@@ -753,4 +771,123 @@ void mcp_list_adrs_for_nonexistent_namespace_returns_error() {
         assertThat(result.isError(), is(true));
         assertThat(text(result), containsString("not found"));
     }
+
+    // --- createArchitectureVersion (POST — no PUT gate) ---
+
+    @Test
+    @Order(66)
+    void mcp_create_architecture_version_with_post() {
+        ToolResponse result = architectureTools.createArchitectureVersion(
+                "finos", createdArchitectureId, "1.2.0", "{\"name\": \"mcp-test-architecture-v2\"}");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("created successfully"));
+        assertThat(text(result), containsString("1.2.0"));
+    }
+
+    @Test
+    @Order(67)
+    void mcp_create_architecture_version_returns_error_for_duplicate() {
+        ToolResponse result = architectureTools.createArchitectureVersion(
+                "finos", createdArchitectureId, "1.2.0", "{\"name\": \"duplicate\"}");
+        assertThat(result.isError(), is(true));
+        assertThat(text(result), containsString("already exists"));
+    }
+
+    @Test
+    @Order(68)
+    void mcp_list_architecture_versions_includes_post_created_version() {
+        ToolResponse result = architectureTools.listArchitectureVersions("finos", createdArchitectureId);
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("1.0.0"));
+        assertThat(text(result), containsString("1.2.0"));
+    }
+
+    // --- Timeline Tools ---
+
+    @Test
+    @Order(69)
+    void mcp_create_timeline() {
+        ToolResponse result = timelineTools.createTimeline("mcp-integration", "MCP Test Timeline", "Integration test timeline", "{\"events\":[]}");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("created successfully"));
+
+        Matcher matcher = ID_PATTERN.matcher(text(result));
+        assertThat("Response should contain timeline ID", matcher.find());
+        createdTimelineId = Integer.parseInt(matcher.group(1));
+        logger.info("Created timeline with ID: {}", createdTimelineId);
+    }
+
+    @Test
+    @Order(70)
+    void mcp_list_timelines_contains_created() {
+        ToolResponse result = timelineTools.listTimelines("mcp-integration");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("MCP Test Timeline"));
+    }
+
+    @Test
+    @Order(71)
+    void mcp_list_timeline_versions() {
+        ToolResponse result = timelineTools.listTimelineVersions("mcp-integration", createdTimelineId);
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("1.0.0"));
+    }
+
+    @Test
+    @Order(72)
+    void mcp_get_timeline() {
+        ToolResponse result = timelineTools.getTimeline("mcp-integration", createdTimelineId, "1.0.0");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("events"));
+    }
+
+    @Test
+    @Order(73)
+    void mcp_create_timeline_version() {
+        ToolResponse result = timelineTools.createTimelineVersion("mcp-integration", createdTimelineId, "1.1.0", "{\"events\":[{\"id\":\"e1\"}]}");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("created successfully"));
+        assertThat(text(result), containsString("1.1.0"));
+    }
+
+    @Test
+    @Order(74)
+    void mcp_list_timeline_versions_includes_new_version() {
+        ToolResponse result = timelineTools.listTimelineVersions("mcp-integration", createdTimelineId);
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("1.0.0"));
+        assertThat(text(result), containsString("1.1.0"));
+    }
+
+    @Test
+    @Order(75)
+    void mcp_create_timeline_version_returns_error_for_duplicate_version() {
+        ToolResponse result = timelineTools.createTimelineVersion("mcp-integration", createdTimelineId, "1.1.0", "{\"events\":[]}");
+        assertThat(result.isError(), is(true));
+        assertThat(text(result), containsString("already exists"));
+    }
+
+    @Test
+    @Order(76)
+    void mcp_update_timeline() {
+        ToolResponse result = timelineTools.updateTimeline("mcp-integration", createdTimelineId, "1.1.0", "{\"events\":[{\"id\":\"e1-updated\"}]}");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("updated successfully"));
+    }
+
+    @Test
+    @Order(77)
+    void mcp_get_timeline_after_update() {
+        ToolResponse result = timelineTools.getTimeline("mcp-integration", createdTimelineId, "1.1.0");
+        assertThat(result.isError(), is(false));
+        assertThat(text(result), containsString("e1-updated"));
+    }
+
+    @Test
+    @Order(78)
+    void mcp_list_timelines_returns_error_for_nonexistent_namespace() {
+        ToolResponse result = timelineTools.listTimelines("nonexistent");
+        assertThat(result.isError(), is(true));
+        assertThat(text(result), containsString("not found"));
+    }
 }

calm-hub/src/integration-test/java/integration/MongoTimelineIntegration.java

@@ -12,6 +12,8 @@
 import org.slf4j.LoggerFactory;
 
 import java.util.ArrayList;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import static io.restassured.RestAssured.given;
 import static integration.MongoSetup.counterSetup;
@@ -27,6 +29,10 @@ public class MongoTimelineIntegration {
     public static final String TIMELINE = "{\"moments\": []}";
     public static final String TIMELINE_V2 = "{\"moments\": [{\"unique-id\": \"1.0.0\"}]}";
 
+    private static final Pattern TIMELINE_ID_PATTERN = Pattern.compile("/timelines/(\\d+)");
+
+    private static int createdTimelineId;
+
     @BeforeEach
     public void setupTimelines() {
         String mongoUri = ConfigProvider.getConfig().getValue("quarkus.mongodb.connection-string", String.class);
@@ -74,20 +80,28 @@ void end_to_end_create_a_timeline() {
                 }
                 """;
 
-        given()
+        String location = given()
                 .body(payload)
                 .header("Content-Type", "application/json")
                 .when().post("/calm/namespaces/finos/timelines")
                 .then()
                 .statusCode(201)
-                .header("Location", containsString("calm/namespaces/finos/timelines/1"));
+                .header("Location", containsString("calm/namespaces/finos/timelines/"))
+                .extract().header("Location");
+
+        Matcher matcher = TIMELINE_ID_PATTERN.matcher(location);
+        if (!matcher.find()) {
+            throw new IllegalStateException("Could not extract timeline ID from Location header: " + location);
+        }
+        createdTimelineId = Integer.parseInt(matcher.group(1));
+        logger.info("Created timeline with ID: {}", createdTimelineId);
     }
 
     @Test
     @Order(3)
     void end_to_end_verify_versions() {
         given()
-                .when().get("/calm/namespaces/finos/timelines/1/versions")
+                .when().get("/calm/namespaces/finos/timelines/" + createdTimelineId + "/versions")
                 .then()
                 .statusCode(200)
                 .body("values", hasSize(1))
@@ -98,7 +112,7 @@ void end_to_end_verify_versions() {
     @Order(4)
     void end_to_end_verify_timeline() {
         given()
-                .when().get("/calm/namespaces/finos/timelines/1/versions/1.0.0")
+                .when().get("/calm/namespaces/finos/timelines/" + createdTimelineId + "/versions/1.0.0")
                 .then()
                 .statusCode(200)
                 .body(equalTo(TIMELINE));
@@ -112,13 +126,13 @@ void end_to_end_create_new_version() {
         given()
                 .body(envelope)
                 .header("Content-Type", "application/json")
-                .when().post("/calm/namespaces/finos/timelines/1/versions/2.0.0")
+                .when().post("/calm/namespaces/finos/timelines/" + createdTimelineId + "/versions/2.0.0")
                 .then()
                 .statusCode(201)
-                .header("Location", containsString("calm/namespaces/finos/timelines/1/versions/2.0.0"));
+                .header("Location", containsString("calm/namespaces/finos/timelines/" + createdTimelineId + "/versions/2.0.0"));
 
         given()
-                .when().get("/calm/namespaces/finos/timelines/1/versions/2.0.0")
+                .when().get("/calm/namespaces/finos/timelines/" + createdTimelineId + "/versions/2.0.0")
                 .then()
                 .statusCode(200)
                 .body(equalTo(TIMELINE_V2));