iac-code 0.1.0__py3-none-any.whl

iac_code/tools/cloud/aliyun/ros_stack_instances.py

@@ -0,0 +1,247 @@
+"""ROS StackGroup Instances tool for Alibaba Cloud Resource Orchestration Service."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any
+
+from alibabacloud_ros20190910 import models as ros_models
+
+from iac_code.i18n import _
+from iac_code.services.cloud_credentials import CloudCredentials
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+from iac_code.tools.cloud.aliyun.ros_client import RosClientFactory
+from iac_code.tools.cloud.types import InstanceStatus
+from iac_code.types.stream_events import StackInstancesProgressEvent
+
+SUPPORTED_ACTIONS = [
+    "CreateStackInstances",
+    "UpdateStackInstances",
+    "DeleteStackInstances",
+]
+
+TERMINAL_STATUSES = {"SUCCEEDED", "FAILED", "STOPPED"}
+DONE_STATUSES = {"SUCCEEDED", "CURRENT", "FAILED", "STOPPED"}
+
+
+class RosStackInstances(Tool):
+    """Alibaba Cloud ROS StackGroup instances lifecycle tool.
+
+    Manages creating, updating, and deleting stack instances within a stack group,
+    with real-time progress polling via operation ID.
+    """
+
+    poll_interval: int = 5
+
+    @property
+    def timeout(self) -> float | None:
+        """Stack instance operations may run for a long time; default to 1 hour."""
+        return 3600.0
+
+    @property
+    def name(self) -> str:
+        return "ros_stack_instances"
+
+    @property
+    def supported_actions(self) -> list[str]:
+        return SUPPORTED_ACTIONS
+
+    @property
+    def description(self) -> str:
+        return (
+            "Manage Alibaba Cloud ROS (Resource Orchestration Service) StackGroup instances lifecycle. "
+            "Supports creating, updating, and deleting stack instances with "
+            "real-time progress polling via operation ID."
+        )
+
+    def _get_default_region(self) -> str:
+        credentials = CloudCredentials()
+        cred = credentials.get_provider("aliyun")
+        return cred.region_id if cred else ""
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        region_desc = "The region to perform the action in."
+        default_region = self._get_default_region()
+        if default_region:
+            region_desc += f" Defaults to '{default_region}'."
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": self.supported_actions,
+                    "description": "The stack instances lifecycle action to perform.",
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Parameters to pass to the action.",
+                },
+                "region_id": {
+                    "type": "string",
+                    "description": region_desc,
+                },
+            },
+            "required": ["action"],
+        }
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        return False
+
+    def is_concurrency_safe(self, tool_input: dict[str, Any]) -> bool:
+        return False
+
+    def is_destructive(self, input: dict | None = None) -> bool:
+        return True
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("CloudStackInstances")
+
+    def _resolve_region(self, input: dict) -> str:
+        return input.get("region_id") or self._get_default_region()
+
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False) -> str | None:
+        action = input.get("action", "")
+        region = self._resolve_region(input)
+        parts = [p for p in [action, region] if p]
+        return " ".join(parts) if parts else None
+
+    def get_activity_description(self, input: dict | None = None) -> str | None:
+        if input is None:
+            return None
+        action = input.get("action", "")
+        region = self._resolve_region(input)
+        display = f"{action} {region}" if region else action
+        return _("Running {action}...").format(action=display)
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False) -> str | None:
+        if verbose:
+            return output.strip()
+        try:
+            data = json.loads(output)
+        except (json.JSONDecodeError, TypeError):
+            return output.strip()[:200]
+        name = data.get("stack_group_name", "")
+        status = data.get("status", "")
+        elapsed = data.get("elapsed_seconds", 0)
+        return f"{name} {status} ({elapsed}s)"
+
+    def _get_client(self, region: str) -> Any:
+        credentials = CloudCredentials()
+        cred = credentials.get_provider("aliyun")
+        return RosClientFactory.create(cred, region_id=region)
+
+    async def _initiate(self, client: Any, action: str, params: dict) -> str:
+        """Start the stack instances operation and return the operation_id."""
+        if action == "CreateStackInstances":
+            request = ros_models.CreateStackInstancesRequest().from_map(params)
+            response = client.create_stack_instances(request)
+            return response.body.operation_id
+        elif action == "UpdateStackInstances":
+            request = ros_models.UpdateStackInstancesRequest().from_map(params)
+            response = client.update_stack_instances(request)
+            return response.body.operation_id
+        elif action == "DeleteStackInstances":
+            request = ros_models.DeleteStackInstancesRequest().from_map(params)
+            response = client.delete_stack_instances(request)
+            return response.body.operation_id
+        raise ValueError(f"Unsupported action: {action}")
+
+    async def _get_operation_status(self, client: Any, operation_id: str, region: str) -> str:
+        """Poll the current status of a stack group operation."""
+        request = ros_models.GetStackGroupOperationRequest(operation_id=operation_id, region_id=region)
+        response = client.get_stack_group_operation(request)
+        return response.body.to_map().get("Status", "RUNNING")
+
+    async def _get_instances(self, client: Any, stack_group_name: str, region: str) -> list[InstanceStatus]:
+        """Get the current list of stack instances for a stack group."""
+        request = ros_models.ListStackInstancesRequest(stack_group_name=stack_group_name, region_id=region)
+        response = client.list_stack_instances(request)
+        data = response.body.to_map()
+        instances = []
+        for item in data.get("StackInstances", []):
+            instances.append(
+                InstanceStatus(
+                    account_id=item.get("AccountId", ""),
+                    region_id=item.get("RegionId", ""),
+                    status=item.get("Status", ""),
+                    status_reason=item.get("StatusReason", ""),
+                    elapsed_seconds=item.get("ElapsedSeconds", 0),
+                )
+            )
+        return instances
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        action = tool_input.get("action", "")
+        if action not in self.supported_actions:
+            return ToolResult.error(f"Invalid action '{action}'. Supported actions: {self.supported_actions}")
+
+        params = tool_input.get("params") or {}
+        region = self._resolve_region(tool_input)
+        stack_group_name = params.get("StackGroupName", "")
+
+        client = self._get_client(region)
+
+        try:
+            operation_id = await self._initiate(client, action, params)
+        except Exception as e:
+            return ToolResult.error(f"[{action}] {e}")
+
+        start_time = time.monotonic()
+
+        while True:
+            await asyncio.sleep(self.__class__.poll_interval)
+
+            try:
+                status = await self._get_operation_status(client, operation_id, region)
+            except Exception as e:
+                return ToolResult.error(f"[GetStackGroupOperation] {e}")
+
+            try:
+                instances = await self._get_instances(client, stack_group_name, region)
+            except Exception as e:
+                return ToolResult.error(f"[ListStackInstances] {e}")
+
+            elapsed = int(time.monotonic() - start_time)
+
+            # Calculate progress percentage based on done instances
+            total_count = len(instances)
+            done_count = sum(1 for inst in instances if inst.status in DONE_STATUSES)
+            progress_percentage = int(done_count / total_count * 100) if total_count > 0 else 0
+
+            if context.event_queue is not None:
+                event = StackInstancesProgressEvent(
+                    stack_group_name=stack_group_name,
+                    operation_id=operation_id,
+                    status=status,
+                    progress_percentage=progress_percentage,
+                    instances=[
+                        {
+                            "account_id": inst.account_id,
+                            "region_id": inst.region_id,
+                            "status": inst.status,
+                            "status_reason": inst.status_reason,
+                            "elapsed_seconds": inst.elapsed_seconds,
+                        }
+                        for inst in instances
+                    ],
+                    elapsed_seconds=elapsed,
+                )
+                await context.event_queue.put(event)
+
+            if status in TERMINAL_STATUSES:
+                is_success = status == "SUCCEEDED"
+                result_data = {
+                    "stack_group_name": stack_group_name,
+                    "operation_id": operation_id,
+                    "status": status,
+                    "progress_percentage": progress_percentage,
+                    "elapsed_seconds": elapsed,
+                    "is_success": is_success,
+                }
+                if is_success:
+                    return ToolResult.success(json.dumps(result_data, ensure_ascii=False, indent=2))
+                else:
+                    return ToolResult.error(json.dumps(result_data, ensure_ascii=False, indent=2))

iac_code/tools/cloud/base_api.py

@@ -0,0 +1,162 @@
+"""Abstract base class for cloud provider API tools."""
+
+from __future__ import annotations
+
+import json
+from abc import abstractmethod
+from typing import Any
+
+from iac_code.i18n import _
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+
+
+class BaseCloudApi(Tool):
+    """Abstract base class for cloud provider API tools.
+
+    Subclasses must implement:
+    - provider_name: Identifies the cloud provider (e.g. "ros", "aws")
+    - supported_actions: List of valid API action names
+    - call_action: Executes the actual API call
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """The cloud provider name (e.g. 'ros')."""
+        ...
+
+    @property
+    @abstractmethod
+    def supported_actions(self) -> list[str]:
+        """List of supported API action names."""
+        ...
+
+    @abstractmethod
+    async def call_action(self, action: str, params: dict, region: str) -> dict:
+        """Execute a cloud API action.
+
+        Args:
+            action: The action name to call.
+            params: Parameters for the action.
+            region: The region to call the action in.
+
+        Returns:
+            The response dict from the cloud API.
+        """
+        ...
+
+    @property
+    def name(self) -> str:
+        return f"{self.provider_name}_api"
+
+    def _get_default_region(self) -> str:
+        """Return the configured default region, or empty string if unknown."""
+        return ""
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        region_desc = "The region to call the action in."
+        default_region = self._get_default_region()
+        if default_region:
+            region_desc += f" Defaults to '{default_region}'."
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": self.supported_actions,
+                    "description": "The API action to call.",
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Parameters to pass to the action.",
+                },
+                "region_id": {
+                    "type": "string",
+                    "description": region_desc,
+                },
+            },
+            "required": ["action"],
+        }
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        if input is None:
+            return False
+        action = input.get("action", "")
+        return action.startswith(("Get", "List", "Describe", "Query", "Validate"))
+
+    def is_concurrency_safe(self, tool_input: dict[str, Any]) -> bool:
+        return self.is_read_only(tool_input)
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("CloudAPI")
+
+    def _resolve_region(self, input: dict) -> str:
+        return input.get("region_id") or self._get_default_region()
+
+    def _get_action_display_detail(self, input: dict) -> str:
+        """Return the key detail to display alongside the action name.
+
+        Defaults to region. Subclasses can override for action-specific display.
+        """
+        return self._resolve_region(input)
+
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False) -> str | None:
+        action = input.get("action", "")
+        detail = self._get_action_display_detail(input)
+        parts = [p for p in [action, detail] if p]
+        return " ".join(parts) if parts else None
+
+    def get_activity_description(self, input: dict | None = None) -> str | None:
+        if input is None:
+            return None
+        action = input.get("action", "")
+        detail = self._get_action_display_detail(input)
+        display = f"{action} {detail}" if detail else action
+        return _("Calling {action}...").format(action=display)
+
+    def _summarize_success_result(self, action: str, result: dict) -> str:
+        """Generate a smart summary of a successful API result.
+
+        Subclasses can override for provider-specific logic.
+        """
+        return _("Call succeeded")
+
+    @staticmethod
+    def _clean_error_message(msg: str) -> str:
+        """Strip raw API response data from error messages."""
+        # Remove trailing " Response: {...}" from SDK exception strings
+        idx = msg.find(" Response: {")
+        if idx > 0:
+            msg = msg[:idx]
+        return msg.strip()
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False) -> str | None:
+        if is_error:
+            return self._clean_error_message(output)
+        if verbose:
+            return output.strip()
+        action = getattr(self, "_last_action", "")
+        result = getattr(self, "_last_result", None)
+        if action and result is not None:
+            return self._summarize_success_result(action, result)
+        lines = output.strip().splitlines()
+        return _("Received response ({count} lines)").format(count=len(lines))
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        action = tool_input.get("action", "")
+        if action not in self.supported_actions:
+            return ToolResult.error(f"Invalid action '{action}'. Supported actions: {self.supported_actions}")
+
+        params = tool_input.get("params") or {}
+        region = self._resolve_region(tool_input)
+
+        try:
+            result = await self.call_action(action, params, region)
+            self._last_action = action
+            self._last_result = result
+            return ToolResult.success(json.dumps(result, ensure_ascii=False, indent=2))
+        except Exception as e:
+            self._last_action = ""
+            self._last_result = None
+            return ToolResult.error(str(e))

iac_code/tools/cloud/base_stack.py

@@ -0,0 +1,242 @@
+"""Abstract base class for cloud provider stack lifecycle tools."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from abc import abstractmethod
+from typing import Any
+
+from iac_code.i18n import _
+from iac_code.tools.base import Tool, ToolContext, ToolResult
+from iac_code.tools.cloud.types import ResourceStatus, StackStatus, translate_status
+from iac_code.types.stream_events import StackProgressEvent
+
+POLL_INTERVAL = 5
+
+
+class BaseCloudStack(Tool):
+    """Abstract base class for cloud provider stack lifecycle tools.
+
+    Subclasses must implement:
+    - provider_name: Identifies the cloud provider (e.g. "ros")
+    - supported_actions: List of valid stack action names
+    - call_action: Starts the stack operation and returns the stack_id
+    - get_stack_status: Polls the current status of a stack
+    - get_stack_resources: Gets the current resource list for a stack
+    """
+
+    poll_interval: int = POLL_INTERVAL
+
+    @property
+    def timeout(self) -> float | None:
+        """Stack operations may run for a long time; default to 1 hour."""
+        return 3600.0
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """The cloud provider name (e.g. 'ros')."""
+        ...
+
+    @property
+    @abstractmethod
+    def supported_actions(self) -> list[str]:
+        """List of supported stack action names."""
+        ...
+
+    @abstractmethod
+    async def call_action(self, action: str, params: dict, region: str) -> str:
+        """Start a stack operation and return the stack_id.
+
+        Args:
+            action: The action name to call.
+            params: Parameters for the action.
+            region: The region to perform the operation in.
+
+        Returns:
+            The stack_id for the created/modified/deleted stack.
+        """
+        ...
+
+    @abstractmethod
+    async def get_stack_status(self, stack_id: str, region: str) -> StackStatus:
+        """Poll the current status of a stack.
+
+        Args:
+            stack_id: The stack identifier.
+            region: The region the stack is in.
+
+        Returns:
+            Current StackStatus.
+        """
+        ...
+
+    @abstractmethod
+    async def get_stack_resources(self, stack_id: str, region: str) -> list[ResourceStatus]:
+        """Get the current resource list for a stack.
+
+        Args:
+            stack_id: The stack identifier.
+            region: The region the stack is in.
+
+        Returns:
+            List of ResourceStatus objects.
+        """
+        ...
+
+    @property
+    def name(self) -> str:
+        return f"{self.provider_name}_stack"
+
+    def _get_default_region(self) -> str:
+        """Return the configured default region, or empty string if unknown."""
+        return ""
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        region_desc = "The region to perform the action in."
+        default_region = self._get_default_region()
+        if default_region:
+            region_desc += f" Defaults to '{default_region}'."
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": self.supported_actions,
+                    "description": "The stack lifecycle action to perform.",
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Parameters to pass to the action.",
+                },
+                "region_id": {
+                    "type": "string",
+                    "description": region_desc,
+                },
+            },
+            "required": ["action"],
+        }
+
+    def is_read_only(self, input: dict | None = None) -> bool:
+        return False
+
+    def is_concurrency_safe(self, tool_input: dict[str, Any]) -> bool:
+        return False
+
+    def is_destructive(self, input: dict | None = None) -> bool:
+        return True
+
+    def user_facing_name(self, input: dict | None = None) -> str:
+        return _("CloudStack")
+
+    def _resolve_region(self, input: dict) -> str:
+        return input.get("region_id") or self._get_default_region()
+
+    def render_tool_use_message(self, input: dict, *, verbose: bool = False) -> str | None:
+        action = input.get("action", "")
+        region = self._resolve_region(input)
+        parts = [p for p in [action, region] if p]
+        return " ".join(parts) if parts else None
+
+    def get_activity_description(self, input: dict | None = None) -> str | None:
+        if input is None:
+            return None
+        action = input.get("action", "")
+        region = self._resolve_region(input)
+        display = f"{action} {region}" if region else action
+        return _("Running {action}...").format(action=display)
+
+    @staticmethod
+    def _clean_error_message(msg: str) -> str:
+        """Strip raw API response data from error messages."""
+        idx = msg.find(" Response: {")
+        if idx > 0:
+            msg = msg[:idx]
+        return msg.strip()
+
+    def render_tool_result_message(self, output: str, *, is_error: bool = False, verbose: bool = False) -> str | None:
+        if verbose:
+            return output.strip()
+        try:
+            data = json.loads(output)
+        except (json.JSONDecodeError, TypeError):
+            if is_error:
+                return self._clean_error_message(output)
+            return output.strip()[:200]
+        name = data.get("stack_name", "")
+        stack_id = data.get("stack_id", "")
+        status = translate_status(data.get("status", ""))
+        elapsed = data.get("elapsed_seconds", 0)
+        label = f"{name}({stack_id})" if stack_id else name
+        return f"{label} {status} ({elapsed}s)"
+
+    async def execute(self, *, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        action = tool_input.get("action", "")
+        if action not in self.supported_actions:
+            return ToolResult.error(f"Invalid action '{action}'. Supported actions: {self.supported_actions}")
+
+        params = tool_input.get("params") or {}
+        region = self._resolve_region(tool_input)
+
+        try:
+            stack_id = await self.call_action(action, params, region)
+        except Exception as e:
+            return ToolResult.error(f"[{action}] {e}")
+
+        start_time = time.monotonic()
+
+        while True:
+            await asyncio.sleep(self._poll_interval)
+
+            try:
+                status = await self.get_stack_status(stack_id, region)
+            except Exception as e:
+                return ToolResult.error(f"[GetStackStatus] {e}")
+
+            try:
+                resources = await self.get_stack_resources(stack_id, region)
+            except Exception as e:
+                return ToolResult.error(f"[GetStackResources] {e}")
+
+            elapsed = int(time.monotonic() - start_time)
+
+            if context.event_queue is not None:
+                event = StackProgressEvent(
+                    stack_id=status.stack_id,
+                    stack_name=status.stack_name,
+                    status=status.status,
+                    progress_percentage=status.progress_percentage,
+                    resources=[
+                        {
+                            "name": r.name,
+                            "resource_type": r.resource_type,
+                            "status": r.status,
+                            "status_reason": r.status_reason,
+                        }
+                        for r in resources
+                    ],
+                    elapsed_seconds=elapsed,
+                )
+                await context.event_queue.put(event)
+
+            if status.is_terminal:
+                result_data = {
+                    "stack_id": status.stack_id,
+                    "stack_name": status.stack_name,
+                    "status": status.status,
+                    "status_reason": status.status_reason,
+                    "progress_percentage": status.progress_percentage,
+                    "elapsed_seconds": elapsed,
+                    "is_success": status.is_success,
+                }
+                if status.is_success:
+                    return ToolResult.success(json.dumps(result_data, ensure_ascii=False, indent=2))
+                else:
+                    return ToolResult.error(json.dumps(result_data, ensure_ascii=False, indent=2))
+
+    @property
+    def _poll_interval(self) -> int:
+        return self.__class__.poll_interval

iac_code/tools/cloud/registry.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from iac_code.services.cloud_credentials import CloudCredentials
+    from iac_code.tools.base import ToolRegistry
+
+
+def register_cloud_tools(registry: "ToolRegistry", credentials: "CloudCredentials") -> None:
+    if credentials.has_provider("aliyun"):
+        from iac_code.tools.cloud.aliyun.aliyun_api import AliyunApi
+        from iac_code.tools.cloud.aliyun.aliyun_doc_search import AliyunDocSearch
+        from iac_code.tools.cloud.aliyun.ros_stack import RosStack
+        from iac_code.tools.cloud.aliyun.ros_stack_instances import RosStackInstances
+
+        registry.register(AliyunApi())
+        registry.register(AliyunDocSearch())
+        registry.register(RosStack())
+        registry.register(RosStackInstances())