feat(utils): split MCP and plugin requirements, add plugin integration tests

.pre-commit-config.yaml

@@ -41,7 +41,7 @@ repos:
         exclude: "^tests/fixtures/|.json|^codegen"
       - id: mixed-line-ending
       - id: name-tests-test
-        exclude: "^tests/main.py"
+        exclude: "^(tests/main\\.py|tests/resources/)"
       - id: requirements-txt-fixer
       - id: trailing-whitespace
         exclude: "docs/source/_static|ATTRIBUTIONS.md||API_REFEREENCE"

requirements/SHR-UTILS-2.md

@@ -0,0 +1,10 @@
+---
+itemId: SHR-UTILS-2
+itemTitle: SDK Plugin System
+itemType: Requirement
+Requirement type: ENVIRONMENT
+---
+
+## Description
+
+Developers shall be able to extend the SDK with custom plugins.

requirements/SWR-UTILS-2-1.md

@@ -0,0 +1,10 @@
+---
+itemId: SWR-UTILS-2-1
+itemTitle: Plugin Module Discovery and Loading
+itemHasParent: SHR-UTILS-2
+itemType: Requirement
+Requirement type: FUNCTIONAL
+Layer: System (backend logic)
+---
+
+System shall discover and load externally installed plugin modules at runtime, making their functionality available without requiring changes to the core SDK codebase.

requirements/SWR-UTILS-2-2.md

@@ -0,0 +1,10 @@
+---
+itemId: SWR-UTILS-2-2
+itemTitle: Plugin CLI Command Integration
+itemHasParent: SHR-UTILS-2
+itemType: Requirement
+Requirement type: FUNCTIONAL
+Layer: System (backend logic)
+---
+
+System shall automatically register CLI commands contributed by plugin modules into the SDK command-line interface.

requirements/SWR-UTILS-2-3.md

@@ -0,0 +1,10 @@
+---
+itemId: SWR-UTILS-2-3
+itemTitle: Plugin GUI Navigation Integration
+itemHasParent: SHR-UTILS-2
+itemType: Requirement
+Requirement type: FUNCTIONAL
+Layer: System (backend logic)
+---
+
+System shall automatically register GUI navigation entries contributed by plugin modules into the SDK graphical user interface.

requirements/SWR-UTILS-2-4.md

@@ -0,0 +1,10 @@
+---
+itemId: SWR-UTILS-2-4
+itemTitle: Plugin MCP Server Integration
+itemHasParent: SHR-UTILS-2
+itemType: Requirement
+Requirement type: FUNCTIONAL
+Layer: System (backend logic)
+---
+
+System shall automatically register MCP servers contributed by plugin modules into the SDK MCP server.

specifications/SPEC-UTILS-SERVICE.md

@@ -3,7 +3,7 @@ itemId: SPEC-UTILS-SERVICE
 itemTitle: Utils Module Specification
 itemType: Software Item Spec
 itemIsRelatedTo: SPEC-GUI-SERVICE, SPEC-BUCKET-SERVICE, SPEC-DATASET-SERVICE, SPEC-NOTEBOOK-SERVICE, SPEC-PLATFORM-SERVICE, SPEC-QUPATH-SERVICE, SPEC-SYSTEM-SERVICE, SPEC-WSI-SERVICE
-itemFulfills: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2, SWR-APPLICATION-2-1, SWR-APPLICATION-2-2, SWR-APPLICATION-2-3, SWR-APPLICATION-2-4, SWR-APPLICATION-2-5, SWR-APPLICATION-2-6, SWR-APPLICATION-2-7, SWR-APPLICATION-2-8, SWR-APPLICATION-2-9, SWR-APPLICATION-2-10, SWR-APPLICATION-2-11, SWR-APPLICATION-2-12, SWR-APPLICATION-2-13, SWR-APPLICATION-2-14, SWR-APPLICATION-2-15, SWR-APPLICATION-2-16, SWR-APPLICATION-3-1, SWR-APPLICATION-3-2, SWR-APPLICATION-3-3, SWR-BUCKET-1-1, SWR-BUCKET-1-2, SWR-BUCKET-1-3, SWR-BUCKET-1-4, SWR-BUCKET-1-5, SWR-BUCKET-1-6, SWR-BUCKET-1-7, SWR-BUCKET-1-8, SWR-BUCKET-1-9, SWR-DATASET-1-1, SWR-DATASET-1-2, SWR-DATASET-1-3, SWR-NOTEBOOK-1-1, SWR-UTILS-1-1, SWR-VISUALIZATION-1-1, SWR-VISUALIZATION-1-2, SWR-VISUALIZATION-1-3, SWR-VISUALIZATION-1-4, SWR_SYSTEM_CLI_HEALTH_1, SWR_SYSTEM_GUI_HEALTH_1, SWR_SYSTEM_GUI_SETTINGS_1
+itemFulfills: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2, SWR-APPLICATION-2-1, SWR-APPLICATION-2-2, SWR-APPLICATION-2-3, SWR-APPLICATION-2-4, SWR-APPLICATION-2-5, SWR-APPLICATION-2-6, SWR-APPLICATION-2-7, SWR-APPLICATION-2-8, SWR-APPLICATION-2-9, SWR-APPLICATION-2-10, SWR-APPLICATION-2-11, SWR-APPLICATION-2-12, SWR-APPLICATION-2-13, SWR-APPLICATION-2-14, SWR-APPLICATION-2-15, SWR-APPLICATION-2-16, SWR-APPLICATION-3-1, SWR-APPLICATION-3-2, SWR-APPLICATION-3-3, SWR-BUCKET-1-1, SWR-BUCKET-1-2, SWR-BUCKET-1-3, SWR-BUCKET-1-4, SWR-BUCKET-1-5, SWR-BUCKET-1-6, SWR-BUCKET-1-7, SWR-BUCKET-1-8, SWR-BUCKET-1-9, SWR-DATASET-1-1, SWR-DATASET-1-2, SWR-DATASET-1-3, SWR-NOTEBOOK-1-1, SWR-UTILS-2-1, SWR-UTILS-2-2, SWR-UTILS-2-3, SWR-UTILS-2-4, SWR-VISUALIZATION-1-1, SWR-VISUALIZATION-1-2, SWR-VISUALIZATION-1-3, SWR-VISUALIZATION-1-4, SWR_SYSTEM_CLI_HEALTH_1, SWR_SYSTEM_GUI_HEALTH_1, SWR_SYSTEM_GUI_SETTINGS_1
 Layer: Infrastructure Service
 Version: 1.0.0
 Date: 2025-10-13
@@ -28,7 +28,10 @@ The Utils Module shall:
 - **[FR-07]** Implement settings management with validation, serialization, and sensitive data handling
 - **[FR-08]** Provide file system utilities for user data directory management and path sanitization
 - **[FR-09]** Support process information gathering and runtime environment detection
-- **[FR-10]** Provide a central MCP server with auto-discovery of plugin tools, namespace isolation, and CLI commands for running the server and listing available tools
+- **[FR-10]** Automatically register MCP servers contributed by plugin modules into the SDK MCP server
+- **[FR-11]** Discover and load externally installed plugin modules at runtime without requiring changes to the core SDK codebase
+- **[FR-12]** Automatically register CLI commands contributed by plugin modules into the SDK command-line interface
+- **[FR-13]** Automatically register GUI navigation entries contributed by plugin modules into the SDK graphical user interface
 
 ### 1.3 Non-Functional Requirements
 

tests/aignostics/utils/TC-UTILS-MCP-01.feature

@@ -4,12 +4,12 @@ Feature: MCP Server Plugin Auto-Discovery
   points, mounts them with namespace isolation, and serves them to MCP clients.
 
   @tests:SPEC-UTILS-SERVICE
-  @tests:SWR-UTILS-1-1
+  @tests:SWR-UTILS-2-4
   @id:TC-UTILS-MCP-01
   Scenario: Server discovers plugin tools via entry points and serves them to a client
     Given a plugin package registers an entry point under "aignostics.plugins"
     And the plugin exposes a FastMCP instance with tools "dummy_echo" and "dummy_add"
-    When the MCP server is created via mcp_create_server()
-    And a client connects and lists tools via client.list_tools()
+    When the SDK MCP server is started
+    And a client connects and lists available tools
     Then the returned tool list includes "dummy_plugin_dummy_echo" and "dummy_plugin_dummy_add"
     And calling "dummy_plugin_dummy_echo" with message "hello" returns "hello"

tests/aignostics/utils/TC-UTILS-PLUGIN-02.feature

@@ -0,0 +1,12 @@
+Feature: Plugin CLI Command Integration
+
+  The SDK automatically registers CLI commands contributed by plugin modules
+  into the SDK command-line interface when the plugin is installed.
+
+  @tests:SWR-UTILS-2-2
+  @id:TC-UTILS-PLUGIN-02
+  Scenario: Plugin CLI commands are registered in the SDK CLI after installation
+    Given a plugin package registers an entry point under "aignostics.plugins"
+    And the plugin exposes a Typer CLI instance
+    When the plugin is installed
+    Then the plugin's CLI commands are available in the SDK command-line interface

tests/aignostics/utils/TC-UTILS-PLUGIN-03.feature

@@ -0,0 +1,12 @@
+Feature: Plugin GUI Navigation Integration
+
+  The SDK automatically registers GUI navigation entries contributed by plugin
+  modules into the SDK graphical user interface when the plugin is installed.
+
+  @tests:SWR-UTILS-2-3
+  @id:TC-UTILS-PLUGIN-03
+  Scenario: Plugin GUI navigation entries are available in the SDK after installation
+    Given a plugin package registers an entry point under "aignostics.plugins"
+    And the plugin exposes a BaseNavBuilder subclass
+    When the SDK GUI collects navigation groups
+    Then the plugin's navigation entries are included in the SDK navigation

tests/aignostics/utils/conftest.py

@@ -0,0 +1,59 @@
+"""Shared fixtures for utils tests."""
+
+from __future__ import annotations
+
+import importlib
+import shutil
+import site
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+DUMMY_PLUGIN_DIR = Path(__file__).resolve().parents[2] / "resources" / "mcp_dummy_plugin"
+
+
+@pytest.fixture(scope="session")
+def install_dummy_plugin() -> Iterator[None]:
+    """Install the dummy plugin package in editable mode for the test session.
+
+    Refreshes site-packages so the running interpreter sees the new package
+    and its entry points without a process restart.
+
+    Note: Plugin discovery caches (discover_plugin_packages, DI caches) may have
+    been populated before this fixture runs. Tests that rely on post-install
+    discovery must pair this fixture with clear_plugin_caches to ensure caches
+    are reset before and after each test.
+
+    Raises:
+        subprocess.CalledProcessError: If install fails, or if uninstall fails for
+            a reason other than the package already being absent.
+    """
+    uv = shutil.which("uv")
+    install_cmd = (
+        [uv, "pip", "install", "--no-deps", "-e", str(DUMMY_PLUGIN_DIR)]
+        if uv
+        else [sys.executable, "-m", "pip", "install", "--no-deps", "-e", str(DUMMY_PLUGIN_DIR)]
+    )
+    # Always use pip for uninstall: uv pip uninstall can fail with exit code 2
+    # for editable installs it did not itself create the dist-info for.
+    uninstall_cmd = [sys.executable, "-m", "pip", "uninstall", "-y", "mcp-dummy-plugin"]
+
+    subprocess.run(install_cmd, check=True, capture_output=True, text=True)
+
+    importlib.invalidate_caches()
+    for sp in site.getsitepackages():
+        site.addsitedir(sp)
+
+    yield
+
+    result = subprocess.run(uninstall_cmd, check=False, capture_output=True, text=True)
+    if result.returncode != 0:
+        output = (result.stderr or result.stdout or "").lower()
+        if not any(marker in output for marker in ("not installed", "no packages found")):
+            raise subprocess.CalledProcessError(result.returncode, result.args, result.stdout, result.stderr)

tests/aignostics/utils/di_test.py

@@ -465,6 +465,9 @@ def test_discover_plugin_packages_is_cached(mock_entry_points: Mock, clear_di_ca
 def test_locate_implementations_searches_plugins(clear_di_caches, record_property) -> None:
     """Test that locate_implementations shallow-scans plugin packages for top-level exports."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    """Test that locate_implementations searches plugin packages."""
+    record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     plugin_instance = AnotherDummyBase()
     mock_plugin_package = ModuleType("test_plugin")
@@ -596,6 +599,7 @@ class _Base:
 def test_locate_implementations_caches_results(clear_di_caches, record_property) -> None:
     """Test that locate_implementations caches results."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     mock_package = MagicMock()
     mock_package.__path__ = []
@@ -640,6 +644,9 @@ class _Base:
 def test_locate_subclasses_searches_plugins(clear_di_caches, record_property) -> None:
     """Test that locate_subclasses shallow-scans plugin packages for top-level exports."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    """Test that locate_subclasses searches plugin packages."""
+    record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     class PluginSubClass(AnotherDummyBase):
         pass
@@ -780,6 +787,7 @@ class MainSub(_Base):
 def test_locate_subclasses_excludes_base_class(clear_di_caches, record_property) -> None:
     """Test that locate_subclasses excludes the base class itself."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     mock_package = _mock_package()
     mock_module = ModuleType("aignostics.testmodule")
@@ -798,6 +806,7 @@ def test_locate_subclasses_excludes_base_class(clear_di_caches, record_property)
 def test_locate_subclasses_caches_results(clear_di_caches, record_property) -> None:
     """Test that locate_subclasses caches results."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     mock_package = MagicMock()
     mock_package.__path__ = []
@@ -817,6 +826,7 @@ def test_locate_subclasses_caches_results(clear_di_caches, record_property) -> N
 def test_locate_subclasses_handles_plugin_import_error(clear_di_caches, record_property) -> None:
     """Test that locate_subclasses handles ImportError for plugin packages gracefully."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     mock_package = MagicMock()
     mock_package.__path__ = []
@@ -838,6 +848,7 @@ def import_side_effect(name: str) -> ModuleType:
 def test_locate_subclasses_handles_module_import_error(clear_di_caches, record_property) -> None:
     """Test that locate_subclasses handles ImportError for individual modules gracefully."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     mock_package = _mock_package()
     call_count = 0
@@ -887,6 +898,7 @@ def test_locate_implementations_and_subclasses_search_both_plugins_and_main_pack
 ) -> None:
     """Test that both functions search plugins first, then main package."""
     record_property("tested-item-id", "SPEC-UTILS-SERVICE")
+    import aignostics.utils._di as di_module
 
     import_order: list[str] = []
 

tests/aignostics/utils/mcp_test.py

@@ -3,9 +3,6 @@
 from __future__ import annotations
 
 import asyncio
-import subprocess
-import sys
-from pathlib import Path
 from typing import TYPE_CHECKING
 from unittest.mock import patch
 
@@ -190,54 +187,13 @@ def test_mcp_list_tools_empty(record_property) -> None:
 # Integration Plugin Auto-Discovery Tests
 # =============================================================================
 
-DUMMY_PLUGIN_DIR = Path(__file__).resolve().parents[2] / "resources" / "mcp_dummy_plugin"
-
 
 def _clear_mcp_discovery_caches() -> None:
     """Invalidate DI and plugin caches so MCP discovery starts fresh."""
     _implementation_cache.pop(FastMCP, None)
     discover_plugin_packages.cache_clear()
 
 
-@pytest.fixture(scope="session")
-def install_dummy_mcp_plugin() -> Iterator[None]:
-    """Install the dummy MCP plugin in editable mode and make it importable.
-
-    Refreshes site-packages so the running interpreter sees the new package
-    and its entry points without a process restart.
-    """
-    import importlib
-    import site
-
-    subprocess.run(
-        [
-            sys.executable,
-            "-m",
-            "pip",
-            "install",
-            "--no-deps",
-            "-e",
-            str(DUMMY_PLUGIN_DIR),
-        ],
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-
-    importlib.invalidate_caches()
-    for sp in site.getsitepackages():
-        site.addsitedir(sp)
-
-    yield
-
-    subprocess.run(
-        [sys.executable, "-m", "pip", "uninstall", "-y", "mcp-dummy-plugin"],
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-
-
 @pytest.fixture
 def clear_mcp_caches() -> Iterator[None]:
     """Clear MCP discovery caches before and after the test."""
@@ -249,9 +205,7 @@ def clear_mcp_caches() -> Iterator[None]:
 @pytest.mark.integration
 @pytest.mark.sequential
 @pytest.mark.timeout(timeout=60)
-def test_mcp_server_discovers_and_serves_plugin_tools(
-    install_dummy_mcp_plugin, clear_mcp_caches, record_property
-) -> None:
+def test_mcp_server_discovers_and_serves_plugin_tools(install_dummy_plugin, clear_mcp_caches, record_property) -> None:
     """Integration: entry point registration -> discovery -> mount -> client round-trip."""
     record_property("tested-item-id", "TC-UTILS-MCP-01")