feat: harden API safety and expand command docs with full test coverage

tests/test_array.py

@@ -20,26 +20,33 @@ def _make_tool():
 
 
 class TestArrayValidation:
-    async def test_destructive_action_requires_confirm(self, _mock_graphql: AsyncMock) -> None:
+    async def test_invalid_action_rejected(self, _mock_graphql: AsyncMock) -> None:
         tool_fn = _make_tool()
-        for action in ("start", "stop", "shutdown", "reboot"):
-            with pytest.raises(ToolError, match="destructive"):
-                await tool_fn(action=action)
+        with pytest.raises(ToolError, match="Invalid action"):
+            await tool_fn(action="start")
 
-    async def test_disk_action_requires_disk_id(self, _mock_graphql: AsyncMock) -> None:
+    async def test_removed_actions_are_invalid(self, _mock_graphql: AsyncMock) -> None:
         tool_fn = _make_tool()
-        for action in ("mount_disk", "unmount_disk", "clear_stats"):
-            with pytest.raises(ToolError, match="disk_id"):
+        for action in (
+            "start",
+            "stop",
+            "shutdown",
+            "reboot",
+            "mount_disk",
+            "unmount_disk",
+            "clear_stats",
+        ):
+            with pytest.raises(ToolError, match="Invalid action"):
                 await tool_fn(action=action)
 
 
 class TestArrayActions:
-    async def test_start_array(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"setState": {"state": "STARTED"}}
+    async def test_parity_start(self, _mock_graphql: AsyncMock) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"start": True}}
         tool_fn = _make_tool()
-        result = await tool_fn(action="start", confirm=True)
+        result = await tool_fn(action="parity_start")
         assert result["success"] is True
-        assert result["action"] == "start"
+        assert result["action"] == "parity_start"
         _mock_graphql.assert_called_once()
 
     async def test_parity_start_with_correct(self, _mock_graphql: AsyncMock) -> None:
@@ -56,45 +63,22 @@ class TestArrayActions:
         result = await tool_fn(action="parity_status")
         assert result["success"] is True
 
-    async def test_mount_disk(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"mountArrayDisk": True}
-        tool_fn = _make_tool()
-        result = await tool_fn(action="mount_disk", disk_id="disk:1")
-        assert result["success"] is True
-        call_args = _mock_graphql.call_args
-        assert call_args[0][1] == {"id": "disk:1"}
-
-    async def test_shutdown(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"shutdown": True}
-        tool_fn = _make_tool()
-        result = await tool_fn(action="shutdown", confirm=True)
-        assert result["success"] is True
-        assert result["action"] == "shutdown"
-
-    async def test_stop_array(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"setState": {"state": "STOPPED"}}
-        tool_fn = _make_tool()
-        result = await tool_fn(action="stop", confirm=True)
-        assert result["success"] is True
-        assert result["action"] == "stop"
-
-    async def test_reboot(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"reboot": True}
-        tool_fn = _make_tool()
-        result = await tool_fn(action="reboot", confirm=True)
-        assert result["success"] is True
-        assert result["action"] == "reboot"
-
     async def test_parity_pause(self, _mock_graphql: AsyncMock) -> None:
         _mock_graphql.return_value = {"parityCheck": {"pause": True}}
         tool_fn = _make_tool()
         result = await tool_fn(action="parity_pause")
         assert result["success"] is True
 
-    async def test_unmount_disk(self, _mock_graphql: AsyncMock) -> None:
-        _mock_graphql.return_value = {"unmountArrayDisk": True}
+    async def test_parity_resume(self, _mock_graphql: AsyncMock) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"resume": True}}
         tool_fn = _make_tool()
-        result = await tool_fn(action="unmount_disk", disk_id="disk:1")
+        result = await tool_fn(action="parity_resume")
+        assert result["success"] is True
+
+    async def test_parity_cancel(self, _mock_graphql: AsyncMock) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"cancel": True}}
+        tool_fn = _make_tool()
+        result = await tool_fn(action="parity_cancel")
         assert result["success"] is True
 
     async def test_generic_exception_wraps(self, _mock_graphql: AsyncMock) -> None:
@@ -107,63 +91,46 @@ class TestArrayActions:
 class TestArrayMutationFailures:
     """Tests for mutation responses that indicate failure."""
 
-    async def test_start_mutation_returns_false(self, _mock_graphql: AsyncMock) -> None:
-        """Mutation returning False in the response field should still succeed (the tool
-        wraps the raw response; it doesn't inspect the inner boolean)."""
-        _mock_graphql.return_value = {"setState": False}
+    async def test_parity_start_mutation_returns_false(self, _mock_graphql: AsyncMock) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"start": False}}
         tool_fn = _make_tool()
-        result = await tool_fn(action="start", confirm=True)
+        result = await tool_fn(action="parity_start")
         assert result["success"] is True
-        assert result["data"] == {"setState": False}
+        assert result["data"] == {"parityCheck": {"start": False}}
 
-    async def test_start_mutation_returns_null(self, _mock_graphql: AsyncMock) -> None:
-        """Mutation returning null for the response field."""
-        _mock_graphql.return_value = {"setState": None}
+    async def test_parity_start_mutation_returns_null(self, _mock_graphql: AsyncMock) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"start": None}}
         tool_fn = _make_tool()
-        result = await tool_fn(action="start", confirm=True)
+        result = await tool_fn(action="parity_start")
         assert result["success"] is True
-        assert result["data"] == {"setState": None}
+        assert result["data"] == {"parityCheck": {"start": None}}
 
-    async def test_start_mutation_returns_empty_object(self, _mock_graphql: AsyncMock) -> None:
-        """Mutation returning an empty object for the response field."""
-        _mock_graphql.return_value = {"setState": {}}
+    async def test_parity_start_mutation_returns_empty_object(
+        self, _mock_graphql: AsyncMock
+    ) -> None:
+        _mock_graphql.return_value = {"parityCheck": {"start": {}}}
         tool_fn = _make_tool()
-        result = await tool_fn(action="start", confirm=True)
+        result = await tool_fn(action="parity_start")
         assert result["success"] is True
-        assert result["data"] == {"setState": {}}
-
-    async def test_mount_disk_mutation_returns_false(self, _mock_graphql: AsyncMock) -> None:
-        """mountArrayDisk returning False indicates mount failed."""
-        _mock_graphql.return_value = {"mountArrayDisk": False}
-        tool_fn = _make_tool()
-        result = await tool_fn(action="mount_disk", disk_id="disk:1")
-        assert result["success"] is True
-        assert result["data"]["mountArrayDisk"] is False
+        assert result["data"] == {"parityCheck": {"start": {}}}
 
     async def test_mutation_timeout(self, _mock_graphql: AsyncMock) -> None:
-        """Mid-operation timeout should be wrapped in ToolError."""
-
         _mock_graphql.side_effect = TimeoutError("operation timed out")
         tool_fn = _make_tool()
         with pytest.raises(ToolError, match="timed out"):
-            await tool_fn(action="shutdown", confirm=True)
+            await tool_fn(action="parity_cancel")
 
 
 class TestArrayNetworkErrors:
     """Tests for network-level failures in array operations."""
 
     async def test_http_500_server_error(self, _mock_graphql: AsyncMock) -> None:
-        """HTTP 500 from the API should be wrapped in ToolError."""
-        mock_response = AsyncMock()
-        mock_response.status_code = 500
-        mock_response.text = "Internal Server Error"
         _mock_graphql.side_effect = ToolError("HTTP error 500: Internal Server Error")
         tool_fn = _make_tool()
         with pytest.raises(ToolError, match="HTTP error 500"):
-            await tool_fn(action="start", confirm=True)
+            await tool_fn(action="parity_start")
 
     async def test_connection_refused(self, _mock_graphql: AsyncMock) -> None:
-        """Connection refused should be wrapped in ToolError."""
         _mock_graphql.side_effect = ToolError("Network connection error: Connection refused")
         tool_fn = _make_tool()
         with pytest.raises(ToolError, match="Network connection error"):