add missing unpackaged metadata option (#3991)

Add support for the Salesforce "unpackaged Metadata" option when
creating package versions.


https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_dev2gp_unpackaged_md.htm

Fixes #3989

Author: yippie

cumulusci/tasks/create_package_version.py

@@ -150,6 +150,11 @@ class CreatePackageVersion(BaseSalesforceApiTask):
             "description": "If True, create unlocked packages for unpackaged metadata in this project and dependencies. "
             "Defaults to False."
         },
+        "unpackaged_metadata_path": {
+            "description": "Path to a directory of metadata to include as unpackaged metadata "
+            "in the package version. This metadata is deployed to the build org during package "
+            "version creation but is not included in the package itself."
+        },
     }
 
     def _init_options(self, kwargs):
@@ -194,6 +199,14 @@ def _init_options(self, kwargs):
         self.options["create_unlocked_dependency_packages"] = process_bool_arg(
             self.options.get("create_unlocked_dependency_packages") or False
         )
+        if "unpackaged_metadata_path" in self.options:
+            unpackaged_metadata_path = pathlib.Path(
+                self.options["unpackaged_metadata_path"]
+            )
+            if not unpackaged_metadata_path.is_dir():
+                raise TaskOptionsError(
+                    f"unpackaged_metadata_path does not exist or is not a directory: {unpackaged_metadata_path}"
+                )
 
     def _init_task(self):
         self.tooling = get_simple_salesforce_connection(
@@ -429,8 +442,27 @@ def _create_version_request(
                         "settings.zip", settings_zip_builder.as_bytes()
                     )
 
-            # Add the dependencies for the package
+            # Add unpackaged metadata if provided (main package only)
             is_dependency = package_config is not self.package_config
+            if "unpackaged_metadata_path" in self.options and not is_dependency:
+                with convert_sfdx_source(
+                    pathlib.Path(self.options["unpackaged_metadata_path"]),
+                    None,
+                    self.logger,
+                ) as unpackaged_path:
+                    unpackaged_metadata_zip_builder = MetadataPackageZipBuilder(
+                        path=unpackaged_path,
+                        context=self.context,
+                    )
+                    version_info.writestr(
+                        "unpackaged-metadata.zip",
+                        unpackaged_metadata_zip_builder.as_bytes(),
+                    )
+                    package_descriptor["unpackagedMetadata"] = {
+                        "path": "unpackaged-metadata.zip"
+                    }
+
+            # Add the dependencies for the package
             if (
                 not (package_config.org_dependent or skip_validation)
                 and not is_dependency

cumulusci/tasks/tests/test_create_package_version.py

@@ -1,3 +1,4 @@
+import base64
 import io
 import json
 import os
@@ -181,6 +182,22 @@ def test_validate_uninstall_script(self):
                 package_type=PackageTypeEnum.unlocked, uninstall_script="Uninstall"
             )  # type: ignore
 
+    def test_unpackaged_metadata_path__missing(self, project_config, org_config):
+        with pytest.raises(TaskOptionsError, match="unpackaged_metadata_path"):
+            CreatePackageVersion(
+                project_config,
+                TaskConfig(
+                    {
+                        "options": {
+                            "package_type": "Managed",
+                            "package_name": "Test Package",
+                            "unpackaged_metadata_path": "/nonexistent/path",
+                        }
+                    }
+                ),
+                org_config,
+            )
+
 
 class TestCreatePackageVersion:
     devhub_base_url = (
@@ -831,3 +848,88 @@ def test_prepare_cci_dependencies(self, task):
         assert task._prepare_cci_dependencies(
             {"ids": [{"subscriberPackageVersionId": "04t000000000000"}]}
         ) == [{"version_id": "04t000000000000"}]
+
+    @responses.activate
+    def test_create_version_request__with_unpackaged_metadata(self, get_task, tmp_path):
+        """unpackaged-metadata.zip and unpackagedMetadata descriptor key are included."""
+        unpackaged_path = tmp_path / "unpackaged_metadata"
+        unpackaged_path.mkdir()
+        (unpackaged_path / "package.xml").write_text(
+            '<?xml version="1.0" encoding="utf-8"?>'
+            '<Package xmlns="http://soap.sforce.com/2006/04/metadata"></Package>'
+        )
+
+        task = get_task(
+            {
+                "package_type": "Managed",
+                "package_name": "Test Package",
+                "unpackaged_metadata_path": str(unpackaged_path),
+            }
+        )
+
+        responses.add(  # query for existing Package2VersionCreateRequest
+            "GET",
+            f"{self.devhub_base_url}/tooling/query/",
+            json={"size": 0, "records": []},
+        )
+        responses.add(  # query for base version number
+            "GET",
+            f"{self.devhub_base_url}/tooling/query/",
+            json={"size": 0, "records": []},
+        )
+        responses.add(  # create Package2VersionCreateRequest
+            "POST",
+            f"{self.devhub_base_url}/tooling/sobjects/Package2VersionCreateRequest/",
+            json={"id": "08c000000000001AAA"},
+        )
+
+        with mock.patch.object(task, "_get_dependencies", return_value=[]):
+            result = task._create_version_request(
+                "0Ho6g000000fy4ZCAQ",
+                task.package_config,
+                BasePackageZipBuilder(),
+            )
+        assert result == "08c000000000001AAA"
+
+        post_body = json.loads(responses.calls[-1].request.body)
+        version_info_zip = zipfile.ZipFile(
+            io.BytesIO(base64.b64decode(post_body["VersionInfo"]))
+        )
+        assert "unpackaged-metadata.zip" in version_info_zip.namelist()
+        descriptor = json.loads(version_info_zip.read("package2-descriptor.json"))
+        assert descriptor["unpackagedMetadata"] == {"path": "unpackaged-metadata.zip"}
+
+    @responses.activate
+    def test_create_version_request__without_unpackaged_metadata(self, task):
+        """unpackaged-metadata.zip is absent when the option is not set."""
+        responses.add(
+            "GET",
+            f"{self.devhub_base_url}/tooling/query/",
+            json={"size": 0, "records": []},
+        )
+        responses.add(
+            "GET",
+            f"{self.devhub_base_url}/tooling/query/",
+            json={"size": 0, "records": []},
+        )
+        responses.add(
+            "POST",
+            f"{self.devhub_base_url}/tooling/sobjects/Package2VersionCreateRequest/",
+            json={"id": "08c000000000001AAA"},
+        )
+
+        with mock.patch.object(task, "_get_dependencies", return_value=[]):
+            result = task._create_version_request(
+                "0Ho6g000000fy4ZCAQ",
+                task.package_config,
+                BasePackageZipBuilder(),
+            )
+        assert result == "08c000000000001AAA"
+
+        post_body = json.loads(responses.calls[-1].request.body)
+        version_info_zip = zipfile.ZipFile(
+            io.BytesIO(base64.b64decode(post_body["VersionInfo"]))
+        )
+        assert "unpackaged-metadata.zip" not in version_info_zip.namelist()
+        descriptor = json.loads(version_info_zip.read("package2-descriptor.json"))
+        assert "unpackagedMetadata" not in descriptor