fix: parse CUMULUSCI_EXTRA_YAML as comma-separated, use pathlib

Splitting the env var on ":" broke on Windows where drive letters
contain colons (e.g. C:\tmp\a.yml). Switch to comma, the convention
used everywhere else in CCI for list-valued strings, via
process_list_arg. Replace os.path.isfile/open with pathlib.Path.
Update all CLI help strings, docstring, and docs.

Author: jstvz

cumulusci/cli/extra_yaml.py

@@ -4,14 +4,16 @@
 kwarg, which already merges into the project config via the existing YAML
 merge stack.
 """
+
 import os
+from pathlib import Path
 from typing import Optional, Tuple
 
 import click
 import yaml
 
 from cumulusci.core.exceptions import CumulusCIUsageError
-from cumulusci.core.utils import dictmerge
+from cumulusci.core.utils import dictmerge, process_list_arg
 
 ENV_VAR = "CUMULUSCI_EXTRA_YAML"
 
@@ -22,7 +24,7 @@ def resolve_extra_yaml(paths: Tuple[str, ...]) -> Optional[str]:
     Args:
         paths: Tuple of paths from Click's ``multiple=True`` option. Empty
             means the flag was not supplied; fall back to
-            ``CUMULUSCI_EXTRA_YAML`` (colon-separated paths).
+            ``CUMULUSCI_EXTRA_YAML`` (comma-separated paths).
 
     Returns:
         A single YAML document representing the deep-merge of all input files
@@ -37,7 +39,7 @@ def resolve_extra_yaml(paths: Tuple[str, ...]) -> Optional[str]:
     if not effective_paths:
         env_value = os.environ.get(ENV_VAR)
         if env_value:
-            effective_paths = tuple(p for p in env_value.split(":") if p)
+            effective_paths = tuple(p for p in (process_list_arg(env_value) or []) if p)
 
     if not effective_paths:
         return None
@@ -51,11 +53,11 @@ def resolve_extra_yaml(paths: Tuple[str, ...]) -> Optional[str]:
 
     merged: dict = {}
     for path in effective_paths:
-        if not os.path.isfile(path):
+        file_path = Path(path)
+        if not file_path.is_file():
             raise CumulusCIUsageError(f"--extra-yaml file not found: {path}")
         try:
-            with open(path, "r", encoding="utf-8") as f:
-                raw = f.read()
+            raw = file_path.read_text(encoding="utf-8")
         except OSError as e:
             raise CumulusCIUsageError(f"--extra-yaml could not read {path}: {e}")
         try:

cumulusci/cli/flow.py

@@ -45,9 +45,9 @@ def flow_doc(runtime, project=False):
     flows_by_group = group_items(flows)
     flow_groups = sorted(
         flows_by_group.keys(),
-        key=lambda group: flow_info_groups.index(group)
-        if group in flow_info_groups
-        else 100,
+        key=lambda group: (
+            flow_info_groups.index(group) if group in flow_info_groups else 100
+        ),
     )
 
     for group in flow_groups:
@@ -116,7 +116,7 @@ def flow_list(runtime, plain, print_json):
         "Path to an additional YAML file to merge into the project config "
         "for this command only. Can be specified multiple times; later files "
         "override earlier ones. Also honors CUMULUSCI_EXTRA_YAML env var "
-        "(colon-separated paths) as a fallback."
+        "(comma-separated paths) as a fallback."
     ),
 )
 @pass_runtime(require_keychain=True)
@@ -164,7 +164,7 @@ def flow_info(runtime, flow_name, extra_yaml):
         "Path to an additional YAML file to merge into the project config "
         "for this command only. Can be specified multiple times; later files "
         "override earlier ones. Also honors CUMULUSCI_EXTRA_YAML env var "
-        "(colon-separated paths) as a fallback."
+        "(comma-separated paths) as a fallback."
     ),
 )
 @pass_runtime(require_keychain=True)

cumulusci/cli/task.py

@@ -105,7 +105,7 @@ def task_doc(runtime, project=False, write=False):
         "Path to an additional YAML file to merge into the project config "
         "for this command only. Can be specified multiple times; later files "
         "override earlier ones. Also honors CUMULUSCI_EXTRA_YAML env var "
-        "(colon-separated paths) as a fallback."
+        "(comma-separated paths) as a fallback."
     ),
 )
 @pass_runtime(require_project=False, require_keychain=True)
@@ -168,7 +168,7 @@ class RunTaskCommand(click.MultiCommand):
                 "Path to an additional YAML file to merge into the project "
                 "config for this command only. Can be specified multiple times; "
                 "later files override earlier ones. Also honors "
-                "CUMULUSCI_EXTRA_YAML env var (colon-separated paths) as a "
+                "CUMULUSCI_EXTRA_YAML env var (comma-separated paths) as a "
                 "fallback."
             ),
             "is_flag": False,

cumulusci/cli/tests/test_extra_yaml.py

@@ -56,15 +56,15 @@ def test_resolve_extra_yaml__env_var_fallback(tmp_path, monkeypatch):
     assert "env-loaded" in result
 
 
-def test_resolve_extra_yaml__env_var_multiple_colon_separated(tmp_path, monkeypatch):
+def test_resolve_extra_yaml__env_var_multiple_comma_separated(tmp_path, monkeypatch):
     """Env var with multiple paths produces a deep-merged document."""
     import yaml
 
     a = tmp_path / "a.yml"
     a.write_text("tasks:\n  a:\n    description: from A\n")
     b = tmp_path / "b.yml"
     b.write_text("tasks:\n  b:\n    description: from B\n")
-    monkeypatch.setenv("CUMULUSCI_EXTRA_YAML", f"{a}:{b}")
+    monkeypatch.setenv("CUMULUSCI_EXTRA_YAML", f"{a},{b}")
     result = resolve_extra_yaml(())
     assert result is not None
     parsed = yaml.safe_load(result)
@@ -87,7 +87,7 @@ def test_resolve_extra_yaml__flag_overrides_env_var(tmp_path, monkeypatch):
 def test_resolve_extra_yaml__empty_env_var_segments_ignored(tmp_path, monkeypatch):
     p = tmp_path / "x.yml"
     p.write_text("project: {}\n")
-    monkeypatch.setenv("CUMULUSCI_EXTRA_YAML", f"::{p}::")
+    monkeypatch.setenv("CUMULUSCI_EXTRA_YAML", f",,{p},,")
     result = resolve_extra_yaml(())
     assert result is not None
     assert "project: {}" in result

docs/cli.md

@@ -492,9 +492,10 @@ $ cci task run my_task --extra-yaml migrations/v2.yml
 $ cci flow run dev_org --extra-yaml base.yml --extra-yaml override.yml
 ```
 
-The `CUMULUSCI_EXTRA_YAML` environment variable (colon-separated paths)
+The `CUMULUSCI_EXTRA_YAML` environment variable (comma-separated paths)
 supplies a default when the flag is absent. When both are set, the flag
-wins; they are not merged.
+wins; they are not merged. Paths containing commas cannot be expressed
+in the env var; pass them via the repeatable `--extra-yaml` flag instead.
 
 Extra YAML is merged using the same deep-merge semantics as the project
 `cumulusci.yml`. Mappings and scalars are overridden; lists are

docs/env-var-reference.md

@@ -18,10 +18,12 @@ orgs.
 
 ## `CUMULUSCI_EXTRA_YAML`
 
-Colon-separated list of paths to additional YAML files to merge into
+Comma-separated list of paths to additional YAML files to merge into
 the project config for each `cci task run`, `cci task info`,
 `cci flow run`, and `cci flow info` invocation. The `--extra-yaml`
-flag on those commands takes precedence when both are set. See
+flag on those commands takes precedence when both are set. Paths
+containing commas cannot be expressed here; use the repeatable
+`--extra-yaml` flag instead. See
 [the CLI reference](cli.md#the-extra-yaml-flag) for merge semantics.
 
 ## `CUMULUSCI_KEY`