(CAT-2433) Adds option to return latest agent build

Adds a command-line option to specify whether the latest agent build should be included in the matrix.
This is due to the Mac and Windows puppet_agent install tasks requiring a specific version when installing.

Author: david22swan

exe/matrix_from_metadata_v3

@@ -163,6 +163,7 @@ begin
     opt.on('--provision-exclude NAME', String, "Filter provisioner (default: #{default_options[:'provision-exclude'] || 'none'})") { |o| options.provision_exclude.push(*o.split(',')) }
 
     opt.on('--nightly', TrueClass, 'Enable nightly builds') { |o| options.nightly = o }
+    opt.on('--latest-agent', TrueClass, 'Return the latest agent build as part of the matrix') { |o| options.latest_agent = o }
   end.parse!
 
   Action.config(debug: true) if options[:debug]
@@ -262,13 +263,33 @@ options[:metadata]['requirements']&.each do |req|
     # This assumes that such a boundary will always allow the latest actually existing puppet version of a release stream, trading off simplicity vs accuracy here.
     next unless gem_req.satisfied_by?(Gem::Version.new("#{collection['puppet'].to_i}.9999"))
 
+    # # If requested, return the latest agent version for the collection's puppet version
+    # # If not requested, return the value latest
+    agent_version = if options[:latest_agent] && collection['puppet'] != 'nightly'
+                      require 'net/http'
+                      require 'json'
+                      require 'uri'
+
+                      require 'pry'
+                      binding.pry
+                      uri = URI('https://forgeapi.puppet.com/private/versions/puppet-agent')
+                      response = Net::HTTP.get_response(uri)
+                      json_data = JSON.parse(response.body)
+                      all_versions = json_data.keys
+                      versionx = all_versions.select { |v| v.start_with?("#{collection['puppet'].to_i}.") }
+                      versionx.sort_by { |v| Gem::Version.new(v) }.last # rubocop:disable Style/RedundantSort
+                    else
+                      'latest'
+                    end
+
     version = collection['puppet'].to_i
     prefix = 'puppetcore'
-    matrix[:collection] << if options[:nightly]
-                             "#{prefix}#{version}-nightly"
-                           else
-                             "#{prefix}#{version}"
-                           end
+    group = if options[:nightly]
+              "#{prefix}#{version}-nightly"
+            else
+              "#{prefix}#{version}"
+            end
+    matrix[:collection] << { collection: group, version: agent_version }
 
     spec_matrix[:include] << {
       puppet_version: "~> #{collection['puppet']}",

spec/exe/matrix_from_metadata_v3_spec.rb

@@ -30,7 +30,7 @@
         '{"label":"Ubuntu-22.04","provider":"docker","arch":"x86_64","image":"litmusimage/ubuntu:22.04","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -63,7 +63,7 @@
         '{"label":"Ubuntu-22.04-arm","provider":"provision_service","arch":"arm","image":"ubuntu-2204-lts-arm64","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -103,7 +103,7 @@
         '{"label":"Ubuntu-22.04-arm","provider":"provision_service","arch":"arm","image":"ubuntu-2204-lts-arm64","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -142,7 +142,7 @@
         '{"label":"Ubuntu-22.04-arm","provider":"provision_service","arch":"arm","image":"ubuntu-2204-lts-arm64","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -175,7 +175,7 @@
         '"platforms":[',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -215,7 +215,7 @@
         '{"label":"Ubuntu-22.04","provider":"docker","arch":"x86_64","image":"litmusimage/ubuntu:22.04","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8"',
+        '{"collection":"puppetcore8","version":"latest"}',
         ']',
         '}'
       ].join
@@ -233,7 +233,7 @@
         '::group::spec_matrix'
       )
       expect(github_output_content).to include(
-        '"collection":["2023.8.4-puppet_enterprise","2021.7.9-puppet_enterprise","puppetcore8"'
+        '"collection":["2023.8.4-puppet_enterprise","2021.7.9-puppet_enterprise",{"collection":"puppetcore8","version":"latest"}'
       )
       expect(github_output_content).to include(
         'spec_matrix={"include":[{"puppet_version":"~> 8.0","ruby_version":3.2}]}'
@@ -257,7 +257,7 @@
         '{"label":"Ubuntu-22.04-arm","provider":"provision_service","arch":"arm","image":"ubuntu-2204-lts-arm64","runner":"ubuntu-latest"}',
         '],',
         '"collection":[',
-        '"puppetcore8-nightly"',
+        '{"collection":"puppetcore8-nightly","version":"latest"}',
         ']',
         '}'
       ].join