feat(cli): add --extra-yaml to cci task run

cci task run uses a custom RunTaskCommand MultiCommand. It must
resolve --extra-yaml before get_task() runs. If it does not, any task
defined only in the extra YAML is invisible to the runtime.

RunTaskCommand.resolve_command reads --extra-yaml from the raw args
list and calls CliRuntime.reload_project_config with the merged YAML.
Both --extra-yaml PATH and --extra-yaml=PATH are accepted.

The peek happens in resolve_command, not in get_command. Click's
MultiCommand protocol calls resolve_command(ctx, args), which then
calls get_command(ctx, cmd_name). By the time get_command runs,
ctx.args is empty. The remaining args stay in the args parameter
passed to resolve_command. We override resolve_command so that we can
see --extra-yaml while the project config is still mutable.

Adds "extra_yaml" to the specials list in core/tasks.py, alongside
debug_before, debug_after, and no_prompt. Click passes extra_yaml as
a kwarg on the task subcommand, which merges into
task_config.config["options"]. Tasks that use the Pydantic Options
form with extra='forbid' would reject it. The specials list already
exists to handle exactly this case.

Author: jstvz

cumulusci/cli/task.py

@@ -121,6 +121,29 @@ def task_info(runtime, task_name, extra_yaml):
     click.echo(rst2ansi(doc))
 
 
+def _peek_extra_yaml(args):
+    """Extract --extra-yaml values from args before Click parses them.
+
+    Matches both ``--extra-yaml PATH`` and ``--extra-yaml=PATH`` forms.
+    Returns a tuple suitable for resolve_extra_yaml().
+    """
+    paths = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--extra-yaml":
+            if i + 1 >= len(args):
+                raise CumulusCIUsageError("--extra-yaml requires a path argument")
+            paths.append(args[i + 1])
+            i += 2
+        elif arg.startswith("--extra-yaml="):
+            paths.append(arg.split("=", 1)[1])
+            i += 1
+        else:
+            i += 1
+    return tuple(paths)
+
+
 class RunTaskCommand(click.MultiCommand):
     # options that are not task specific
     global_options = {
@@ -140,13 +163,38 @@ class RunTaskCommand(click.MultiCommand):
             "help": "Drops into the Python debugger at task completion.",
             "is_flag": True,
         },
+        "extra-yaml": {
+            "help": (
+                "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."
+            ),
+            "is_flag": False,
+            "multiple": True,
+        },
     }
 
     def list_commands(self, ctx):
         runtime = ctx.obj
         tasks = runtime.get_available_tasks()
         return sorted([t["name"] for t in tasks])
 
+    def resolve_command(self, ctx, args):
+        # Peek at --extra-yaml / CUMULUSCI_EXTRA_YAML before Click resolves
+        # the task. Click's MultiCommand protocol calls resolve_command ->
+        # get_command; by the time get_command runs, ctx.args is empty. We
+        # read from the raw `args` list here so --extra-yaml values are
+        # available before get_task() runs.
+        runtime = ctx.obj
+        if runtime is not None and runtime.project_config is not None:
+            extra_yaml_paths = _peek_extra_yaml(args)
+            runtime.reload_project_config(
+                additional_yaml=resolve_extra_yaml(extra_yaml_paths)
+            )
+        return super().resolve_command(ctx, args)
+
     def get_command(self, ctx, task_name):
         runtime = ctx.obj
         if runtime.project_config is None:
@@ -285,6 +333,7 @@ def _get_default_command_options(self, is_salesforce_task):
                 click.Option(
                     param_decls=(f"--{opt_name}",),
                     is_flag=config["is_flag"],
+                    multiple=config.get("multiple", False),
                     help=config["help"],
                 )
             )

cumulusci/cli/tests/test_task.py

@@ -49,6 +49,58 @@ def test_task_run(runtime):
     DummyTask._run_task.assert_called_once()
 
 
+def test_task_run__extra_yaml_applied(runtime, tmp_path):
+    """--extra-yaml resolves via resolve_command before get_task runs."""
+    extra = tmp_path / "extra.yml"
+    extra.write_text(
+        "tasks:\n  dummy-task:\n    description: Overridden from --extra-yaml\n"
+    )
+
+    DummyTask._run_task = Mock()
+    runtime.reload_project_config = Mock()
+    multi_cmd = task.RunTaskCommand()
+    with click.Context(multi_cmd, obj=runtime) as ctx:
+        multi_cmd.resolve_command(ctx, ["dummy-task", "--extra-yaml", str(extra)])
+
+    runtime.reload_project_config.assert_called_once()
+    call_kwargs = runtime.reload_project_config.call_args.kwargs
+    assert "Overridden from --extra-yaml" in call_kwargs["additional_yaml"]
+
+
+def test_task_run__extra_yaml_equals_syntax(runtime, tmp_path):
+    """--extra-yaml=<path> form is also accepted."""
+    extra = tmp_path / "extra.yml"
+    extra.write_text("tasks:\n  dummy-task:\n    description: eq-syntax\n")
+
+    DummyTask._run_task = Mock()
+    runtime.reload_project_config = Mock()
+    multi_cmd = task.RunTaskCommand()
+    with click.Context(multi_cmd, obj=runtime) as ctx:
+        multi_cmd.resolve_command(ctx, ["dummy-task", f"--extra-yaml={extra}"])
+
+    runtime.reload_project_config.assert_called_once()
+    assert (
+        "eq-syntax" in runtime.reload_project_config.call_args.kwargs["additional_yaml"]
+    )
+
+
+def test_task_run__no_extra_yaml_still_calls_reload_with_none(runtime):
+    DummyTask._run_task = Mock()
+    runtime.reload_project_config = Mock()
+    multi_cmd = task.RunTaskCommand()
+    with click.Context(multi_cmd, obj=runtime) as ctx:
+        multi_cmd.resolve_command(ctx, ["dummy-task"])
+
+    runtime.reload_project_config.assert_called_once_with(additional_yaml=None)
+
+
+def test_task_run__extra_yaml_missing_path_raises(runtime):
+    multi_cmd = task.RunTaskCommand()
+    with click.Context(multi_cmd, obj=runtime) as ctx:
+        with pytest.raises(CumulusCIUsageError, match="requires a path"):
+            multi_cmd.resolve_command(ctx, ["dummy-task", "--extra-yaml"])
+
+
 def test_task_run__no_project(runtime):
     runtime.project_config = None
     runtime.project_config_error = Exception("Broken")
@@ -110,6 +162,18 @@ def test_task_run__list_commands(runtime):
     assert commands == ["dummy-derived-task", "dummy-task"]
 
 
+def test_task_run__list_commands_with_extra_yaml_in_args(runtime, tmp_path):
+    """--help paths reach list_commands/format_help directly, not through
+    resolve_command. --extra-yaml in the arg vector must not break them."""
+    extra = tmp_path / "extra.yml"
+    extra.write_text("tasks:\n  dummy-task:\n    description: from extra\n")
+    multi_cmd = task.RunTaskCommand()
+    with click.Context(multi_cmd, obj=runtime) as ctx:
+        ctx.args = ["--extra-yaml", str(extra)]
+        commands = multi_cmd.list_commands(ctx)
+    assert "dummy-task" in commands
+
+
 def test_format_help(runtime):
     runtime.universal_config = Mock()
     multi_cmd = task.RunTaskCommand()
@@ -126,11 +190,12 @@ def test_format_help(runtime):
 
 def test_get_default_command_options():
     opts = task.RunTaskCommand()._get_default_command_options(is_salesforce_task=False)
-    assert len(opts) == 4
+    assert len(opts) == 5
 
     opts = task.RunTaskCommand()._get_default_command_options(is_salesforce_task=True)
-    assert len(opts) == 5
+    assert len(opts) == 6
     assert any([o.name == "org" for o in opts])
+    assert any([o.name == "extra_yaml" for o in opts])
 
 
 def test_collect_task_options():

cumulusci/core/tasks.py

@@ -158,7 +158,7 @@ def process_options(option):
 
         if self.Options:
             try:
-                specials = ["debug_before", "debug_after", "no_prompt"]
+                specials = ["debug_before", "debug_after", "no_prompt", "extra_yaml"]
                 options_without_specials = {
                     opt: val for opt, val in self.options.items() if opt not in specials
                 }