lucius-mcp 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

src/services/__init__.py

@@ -1,9 +1,17 @@
 """Service layer modules for lucius-mcp."""
 
 from .attachment_service import AttachmentService
+from .custom_field_value_service import CustomFieldValueService
 from .search_service import SearchService
 from .shared_step_service import SharedStepService
 from .test_case_service import TestCaseService
 from .test_layer_service import TestLayerService
 
-__all__ = ["AttachmentService", "SearchService", "SharedStepService", "TestCaseService", "TestLayerService"]
+__all__ = [
+    "AttachmentService",
+    "CustomFieldValueService",
+    "SearchService",
+    "SharedStepService",
+    "TestCaseService",
+    "TestLayerService",
+]

src/services/custom_field_value_service.py

@@ -0,0 +1,301 @@
+"""Service for managing Custom Field Values in Allure TestOps."""
+
+import logging
+
+from pydantic import ValidationError as PydanticValidationError
+
+from src.client import AllureClient
+from src.client.exceptions import AllureAPIError, AllureNotFoundError, AllureValidationError
+from src.client.generated.models.custom_field_value_project_create_dto import CustomFieldValueProjectCreateDto
+from src.client.generated.models.custom_field_value_project_patch_dto import CustomFieldValueProjectPatchDto
+from src.client.generated.models.custom_field_value_with_cf_dto import CustomFieldValueWithCfDto
+from src.client.generated.models.id_only_dto import IdOnlyDto
+from src.client.generated.models.page_custom_field_value_with_tc_count_dto import PageCustomFieldValueWithTcCountDto
+from src.services.test_case_service import ResolvedCustomFieldInfo, TestCaseService
+from src.utils.schema_hint import generate_schema_hint
+
+logger = logging.getLogger(__name__)
+
+MAX_NAME_LENGTH = 255
+
+
+class CustomFieldValueService:
+    """Service for CRUD operations on custom field values."""
+
+    def __init__(self, client: AllureClient) -> None:
+        self._client = client
+        self._project_id = client.get_project()
+        self._test_case_service = TestCaseService(client=client)
+
+    async def list_custom_field_values(
+        self,
+        *,
+        project_id: int | None = None,
+        custom_field_id: int | None = None,
+        custom_field_name: str | None = None,
+        query: str | None = None,
+        var_global: bool | None = None,
+        test_case_search: str | None = None,
+        page: int | None = None,
+        size: int | None = None,
+        sort: list[str] | None = None,
+    ) -> PageCustomFieldValueWithTcCountDto:
+        """List custom field values for a project-scoped custom field."""
+        resolved_project_id = self._resolve_project_id(project_id)
+        resolved_custom_field_id = await self._resolve_custom_field_id(
+            resolved_project_id,
+            custom_field_id=custom_field_id,
+            custom_field_name=custom_field_name,
+        )
+
+        return await self._client.list_custom_field_values(
+            project_id=resolved_project_id,
+            custom_field_id=resolved_custom_field_id,
+            query=query,
+            var_global=var_global,
+            test_case_search=test_case_search,
+            page=page,
+            size=size,
+            sort=sort,
+        )
+
+    async def create_custom_field_value(
+        self,
+        *,
+        project_id: int | None = None,
+        custom_field_id: int | None = None,
+        custom_field_name: str | None = None,
+        name: str,
+    ) -> CustomFieldValueWithCfDto:
+        """Create a new custom field value for the given field."""
+        resolved_project_id = self._resolve_project_id(project_id)
+        resolved_custom_field_id = await self._resolve_custom_field_id(
+            resolved_project_id,
+            custom_field_id=custom_field_id,
+            custom_field_name=custom_field_name,
+        )
+        self._validate_name(name)
+
+        try:
+            dto = CustomFieldValueProjectCreateDto(
+                custom_field=IdOnlyDto(id=resolved_custom_field_id),
+                name=name,
+                project_id=resolved_project_id,
+            )
+        except PydanticValidationError as exc:
+            hint = generate_schema_hint(CustomFieldValueProjectCreateDto)
+            raise AllureValidationError(f"Invalid custom field value data: {exc}", suggestions=[hint]) from exc
+
+        try:
+            created = await self._client.create_custom_field_value(resolved_project_id, dto)
+        except AllureValidationError as exc:
+            if exc.status_code in (400, 409, 422):
+                raise AllureValidationError(
+                    "Custom field value already exists or is invalid.",
+                    status_code=exc.status_code,
+                    response_body=exc.response_body,
+                    suggestions=[
+                        "Use a unique name for the custom field value",
+                        "List existing values with list_custom_field_values",
+                    ],
+                ) from exc
+            raise
+        except AllureAPIError as exc:
+            if exc.status_code in (400, 409, 422):
+                raise AllureValidationError(
+                    "Custom field value already exists or is invalid.",
+                    status_code=exc.status_code,
+                    response_body=exc.response_body,
+                    suggestions=[
+                        "Use a unique name for the custom field value",
+                        "List existing values with list_custom_field_values",
+                    ],
+                ) from exc
+            raise
+        await self._test_case_service.refresh_resolved_custom_fields(resolved_project_id)
+        return created
+
+    async def update_custom_field_value(
+        self,
+        *,
+        project_id: int | None = None,
+        cfv_id: int | None = None,
+        custom_field_id: int | None = None,
+        custom_field_name: str | None = None,
+        name: str | None = None,
+        force: bool = False,
+    ) -> None:
+        """Update a custom field value (rename)."""
+        resolved_project_id = self._resolve_project_id(project_id)
+        resolved_custom_field_id = await self._resolve_custom_field_id(
+            resolved_project_id,
+            custom_field_id=custom_field_id,
+            custom_field_name=custom_field_name,
+        )
+
+        resolved_cfv_id, usage_count = await self._resolve_cfv_and_check_usage(
+            resolved_project_id,
+            resolved_custom_field_id,
+            cfv_id=cfv_id,
+            cfv_name=None,  # We don't support finding by name for update yet based on existing params
+        )
+
+        self._validate_cfv_id(resolved_cfv_id)
+        if name is None:
+            raise AllureValidationError("Name is required for update")
+        self._validate_name(name)
+
+        if usage_count > 0 and not force:
+            raise AllureValidationError(
+                f"Custom field value is used in {usage_count} test cases. Use force=True to proceed."
+            )
+
+        try:
+            dto = CustomFieldValueProjectPatchDto(name=name)
+        except PydanticValidationError as exc:
+            hint = generate_schema_hint(CustomFieldValueProjectPatchDto)
+            raise AllureValidationError(f"Invalid custom field value patch data: {exc}", suggestions=[hint]) from exc
+
+        await self._client.update_custom_field_value(resolved_project_id, resolved_cfv_id, dto)
+        await self._test_case_service.refresh_resolved_custom_fields(resolved_project_id)
+
+    async def delete_custom_field_value(
+        self,
+        *,
+        project_id: int | None = None,
+        cfv_id: int | None = None,
+        cfv_name: str | None = None,
+        custom_field_id: int | None = None,
+        custom_field_name: str | None = None,
+        force: bool = False,
+    ) -> bool:
+        """Delete a custom field value (idempotent).
+
+        Returns True if deletion occurred, False if the value was already removed.
+        """
+        resolved_project_id = self._resolve_project_id(project_id)
+        resolved_custom_field_id = await self._resolve_custom_field_id(
+            resolved_project_id,
+            custom_field_id=custom_field_id,
+            custom_field_name=custom_field_name,
+        )
+
+        try:
+            resolved_cfv_id, usage_count = await self._resolve_cfv_and_check_usage(
+                resolved_project_id,
+                resolved_custom_field_id,
+                cfv_id=cfv_id,
+                cfv_name=cfv_name,
+            )
+        except AllureValidationError:
+            # If resolving fails (e.g. not found), treat as idempotent access if filtering by ID?
+            # If scanning by name fails, it doesn't exist.
+            logger.debug("Custom field value not found for deletion")
+            return False
+
+        if usage_count > 0 and not force:
+            raise AllureValidationError(
+                f"Custom field value is used in {usage_count} test cases. Use force=True to proceed."
+            )
+
+        self._validate_cfv_id(resolved_cfv_id)
+
+        try:
+            await self._client.delete_custom_field_value(resolved_project_id, resolved_cfv_id)
+            await self._test_case_service.refresh_resolved_custom_fields(resolved_project_id)
+            return True
+        except AllureNotFoundError:
+            logger.debug("Custom field value %s already removed", resolved_cfv_id)
+            return False
+
+    async def _resolve_cfv_and_check_usage(
+        self,
+        project_id: int,
+        custom_field_id: int,
+        cfv_id: int | None,
+        cfv_name: str | None,
+    ) -> tuple[int, int]:
+        """Resolve CFV ID and usage count.
+
+        Returns (cfv_id, usage_count).
+        """
+        if cfv_id is None and not (cfv_name and cfv_name.strip()):
+            raise AllureValidationError("Either cfv_id or cfv_name must be provided")
+
+        query = cfv_name if cfv_name else None
+        # List values to find usage and ID
+        page = await self.list_custom_field_values(
+            project_id=project_id,
+            custom_field_id=custom_field_id,
+            query=query,
+            size=100,  # Fetch enough to hopefully find it
+        )
+
+        found = None
+        for item in page.content or []:
+            if cfv_id is not None:
+                if item.id == cfv_id:
+                    found = item
+                    break
+            elif cfv_name:
+                if item.name == cfv_name:
+                    found = item
+                    break
+
+        if found:
+            return found.id or 0, found.test_cases_count or 0
+
+        if cfv_id is not None:
+            # If ID passed but not found in list (maybe truncated?), we assume usage is unknown(unsafe) or 0?
+            # For safety, if we can't verify usage, we might warn.
+            # But if ID exists but is not in first 1000, we can't check usage easily.
+            # Let's return ID and 0 usage but log warning?
+            # Or rely on client to handle 404 if invalid.
+            return cfv_id, 0
+
+        raise AllureValidationError(f"Custom field value specificied by name '{cfv_name}' not found")
+
+    def _resolve_project_id(self, project_id: int | None) -> int:
+        resolved_project_id = project_id if project_id is not None else self._project_id
+        if not isinstance(resolved_project_id, int) or resolved_project_id <= 0:
+            raise AllureValidationError("Project ID must be a positive integer")
+        return resolved_project_id
+
+    async def _resolve_custom_field_id(
+        self,
+        project_id: int,
+        *,
+        custom_field_id: int | None,
+        custom_field_name: str | None,
+    ) -> int:
+        if custom_field_id is not None:
+            if not isinstance(custom_field_id, int) or custom_field_id == 0:
+                raise AllureValidationError("Custom Field ID must be a non-zero integer")
+            return custom_field_id
+
+        if custom_field_name is None or not custom_field_name.strip():
+            raise AllureValidationError("Custom field name is required when custom_field_id is not provided")
+
+        mapping = await self._get_resolved_custom_fields(project_id)
+        normalized_name = custom_field_name.strip()
+        info = mapping.get(normalized_name)
+        if info is None:
+            suggestions = sorted(mapping.keys())
+            raise AllureValidationError(
+                f"Custom field '{normalized_name}' not found.",
+                suggestions=suggestions if suggestions else ["Use get_custom_fields to list available fields."],
+            )
+        return info["project_cf_id"]
+
+    async def _get_resolved_custom_fields(self, project_id: int) -> dict[str, ResolvedCustomFieldInfo]:
+        return await self._test_case_service._get_resolved_custom_fields(project_id)
+
+    def _validate_name(self, name: str) -> None:
+        if not name or not name.strip():
+            raise AllureValidationError("Name is required")
+        if len(name) > MAX_NAME_LENGTH:
+            raise AllureValidationError(f"Name too long (max {MAX_NAME_LENGTH})")
+
+    def _validate_cfv_id(self, cfv_id: int) -> None:
+        if not isinstance(cfv_id, int) or cfv_id <= 0:
+            raise AllureValidationError("Custom Field Value ID must be a positive integer")

src/services/integration_service.py

@@ -0,0 +1,205 @@
+"""Service for managing Integrations in Allure TestOps."""
+
+import logging
+
+from src.client import AllureClient
+from src.client.exceptions import AllureAPIError, AllureNotFoundError, AllureValidationError
+from src.client.generated.models.integration_dto import IntegrationDto
+
+logger = logging.getLogger(__name__)
+
+
+class IntegrationService:
+    """Service for managing Integrations in Allure TestOps.
+
+    Integrations are external issue trackers (Jira, GitHub, etc.) that are configured
+    at the instance level. This service provides methods to discover available integrations
+    and resolve integration IDs for use in issue linking.
+    """
+
+    def __init__(self, client: AllureClient) -> None:
+        """Initialize IntegrationService.
+
+        Args:
+            client: AllureClient instance
+        """
+        self._client = client
+
+    async def list_integrations(self) -> list[IntegrationDto]:
+        """List all available integrations.
+
+        Returns:
+            List of IntegrationDto objects
+
+        Raises:
+            AllureAPIError: If the API request fails
+        """
+        return await self._client.get_integrations()
+
+    async def get_integration_by_id(self, integration_id: int) -> IntegrationDto:
+        """Get an integration by its ID.
+
+        Args:
+            integration_id: The unique ID of the integration
+
+        Returns:
+            The IntegrationDto
+
+        Raises:
+            AllureNotFoundError: If integration doesn't exist
+            AllureValidationError: If the ID is invalid
+            AllureAPIError: If the API request fails
+        """
+        if integration_id <= 0:
+            raise AllureValidationError("Integration ID must be a positive integer")
+
+        integrations = await self.list_integrations()
+        for integration in integrations:
+            if integration.id == integration_id:
+                return integration
+
+        raise AllureNotFoundError(
+            f"Integration with ID {integration_id} not found. "
+            f"Available integrations: {self._format_integration_list(integrations)}"
+        )
+
+    async def get_integration_by_name(self, name: str) -> IntegrationDto:
+        """Get an integration by its exact name (case-sensitive).
+
+        Args:
+            name: The exact name of the integration
+
+        Returns:
+            The IntegrationDto
+
+        Raises:
+            AllureNotFoundError: If integration doesn't exist
+            AllureValidationError: If the name is empty
+            AllureAPIError: If the API request fails
+        """
+        if not name or not name.strip():
+            raise AllureValidationError("Integration name is required")
+
+        integrations = await self.list_integrations()
+        for integration in integrations:
+            if integration.name == name:
+                return integration
+
+        raise AllureNotFoundError(
+            f"Integration '{name}' not found. Available integrations: {self._format_integration_list(integrations)}"
+        )
+
+    async def resolve_integration(
+        self,
+        integration_id: int | None = None,
+        integration_name: str | None = None,
+    ) -> IntegrationDto | None:
+        """Resolve an integration from either ID or name.
+
+        This method handles mutual exclusivity validation and resolution.
+
+        Args:
+            integration_id: Optional integration ID
+            integration_name: Optional integration name
+
+        Returns:
+            The resolved IntegrationDto if either parameter is provided, None otherwise
+
+        Raises:
+            AllureValidationError: If both parameters are provided (mutual exclusivity)
+            AllureNotFoundError: If the specified integration doesn't exist
+            AllureAPIError: If the API request fails
+        """
+        # 1. Mutual exclusivity check
+        if integration_id is not None and integration_name is not None:
+            raise AllureValidationError(
+                "Cannot specify both 'integration_id' and 'integration_name'. "
+                "Use only one parameter to identify the integration."
+            )
+
+        # 2. Resolve by ID
+        if integration_id is not None:
+            return await self.get_integration_by_id(integration_id)
+
+        # 3. Resolve by Name
+        if integration_name is not None:
+            return await self.get_integration_by_name(integration_name)
+
+        # 4. Neither provided
+        return None
+
+    async def resolve_integration_for_issues(
+        self,
+        integration_id: int | None = None,
+        integration_name: str | None = None,
+    ) -> int:
+        """Resolve integration ID for issue linking with strict behavior.
+
+        This method enforces AC#6 and AC#7:
+        - Single integration: Auto-select
+        - Multiple integrations: Error if no selection provided
+
+        Args:
+            integration_id: Optional integration ID to use
+            integration_name: Optional integration name to use
+
+        Returns:
+            The resolved integration ID
+
+        Raises:
+            AllureValidationError: If multiple integrations exist and none specified,
+                                  or if both parameters are provided
+            AllureNotFoundError: If the specified integration doesn't exist
+            AllureAPIError: If the API request fails or no integrations configured
+        """
+        # First check if explicit integration is provided
+        resolved = await self.resolve_integration(integration_id, integration_name)
+        if resolved:
+            if resolved.id is None:
+                raise AllureAPIError("Resolved integration has no ID")
+            return resolved.id
+
+        # No explicit selection - check available integrations
+        integrations = await self.list_integrations()
+
+        if not integrations:
+            raise AllureAPIError(
+                "No integrations configured in Allure TestOps. "
+                "Please configure an integration (Jira, GitHub, etc.) before linking issues."
+            )
+
+        if len(integrations) == 1:
+            # AC#6: Single integration - auto-select
+            if integrations[0].id is None:
+                raise AllureAPIError("Integration has no ID")
+            return integrations[0].id
+
+        # AC#7: Multiple integrations - require explicit selection
+        raise AllureValidationError(
+            f"Multiple integrations found. Please specify which integration to use.\n"
+            f"Available integrations:\n{self._format_integration_list(integrations)}\n\n"
+            "Hint: Use 'integration_id' or 'integration_name' parameter to specify the integration."
+        )
+
+    def _format_integration_list(self, integrations: list[IntegrationDto]) -> str:
+        """Format a list of integrations for display in error messages.
+
+        Args:
+            integrations: List of IntegrationDto objects
+
+        Returns:
+            Formatted string with integration names and IDs
+        """
+        if not integrations:
+            return "(none configured)"
+
+        lines: list[str] = []
+        for integration in integrations:
+            name = integration.name or "(unnamed)"
+            int_id = integration.id or "N/A"
+            info_type = ""
+            if integration.info and hasattr(integration.info, "type") and integration.info.type:
+                info_type = f" [{integration.info.type}]"
+            lines.append(f"- {name} (ID: {int_id}){info_type}")
+
+        return "\n".join(lines)

src/services/launch_service.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from pydantic import ValidationError as PydanticValidationError
 
 from src.client import AllureClient, FindAll29200Response, LaunchCreateDto, LaunchDto
-from src.client.exceptions import AllureValidationError
+from src.client.exceptions import AllureNotFoundError, AllureValidationError, LaunchNotFoundError
 from src.client.generated.models.aql_validate_response_dto import AqlValidateResponseDto
 from src.client.generated.models.external_link_dto import ExternalLinkDto
 from src.client.generated.models.issue_dto import IssueDto
@@ -173,6 +173,27 @@ class LaunchService:
             total_pages=response.total_pages or 1,
         )
 
+    async def get_launch(self, launch_id: int) -> LaunchDto:
+        """Retrieve a specific launch by its ID.
+
+        Args:
+            launch_id: The unique ID of the launch.
+
+        Returns:
+            The launch data.
+        """
+        self._validate_project_id(self._project_id)
+        self._validate_launch_id(launch_id)
+
+        try:
+            return await self._client.get_launch(launch_id)
+        except AllureNotFoundError as exc:
+            raise LaunchNotFoundError(
+                launch_id=launch_id,
+                status_code=exc.status_code,
+                response_body=exc.response_body,
+            ) from exc
+
     async def validate_launch_query(self, rql: str) -> tuple[bool, int | None]:
         """Validate an AQL query for launches."""
         if not isinstance(rql, str) or not rql.strip():
@@ -203,6 +224,13 @@ class LaunchService:
         if not isinstance(size, int) or size <= 0 or size > 100:
             raise AllureValidationError("Size must be between 1 and 100")
 
+    @staticmethod
+    def _validate_launch_id(launch_id: int) -> None:
+        if not isinstance(launch_id, int):
+            raise AllureValidationError(f"Launch ID must be an integer, got {type(launch_id).__name__}")
+        if launch_id <= 0:
+            raise AllureValidationError("Launch ID must be a positive integer")
+
     @staticmethod
     def _validate_name(name: str) -> None:
         if not isinstance(name, str):