🐛 fix(toml): extract args from Command in ref replacement (#3863)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: gaborbernat

docs/changelog/3830.bugfix.rst

@@ -0,0 +1,3 @@
+Command-type configuration values like ``list_dependencies_command`` can now be referenced in TOML using the structured
+``{replace = "ref"}`` syntax. The reference automatically extracts the command's argument list for compatibility with
+TOML's ``list[list[str]]`` structure - by :user:`gaborbernat`.

docs/reference/config.rst

@@ -1920,7 +1920,8 @@ Pip installer
 
     The ``list_dependencies_command`` setting is used for listing the packages installed into the virtual environment.
     This command will be executed only if executing on Continuous Integrations is detected (for example set environment
-    variable ``CI=1``) or if journal is active.
+    variable ``CI=1``) or if journal is active. In TOML configurations, reference this Command value using
+    ``{replace = "ref"}`` with ``extend = true`` rather than string interpolation.
 
 .. conf::
     :keys: pip_pre
@@ -2164,6 +2165,18 @@ You can reference other configurations via the ``ref`` replacement. This can eit
 The ``extend`` flag controls if after replacement the value should be replaced as is in the host structure (when flag is
 false -- by default) or be extended into. This flag only operates when the host is a list.
 
+When referencing Command-type configuration values (like ``list_dependencies_command``), the reference automatically
+extracts the command's argument list, making it compatible with TOML's structured ``commands`` format. For example:
+
+    .. code-block:: toml
+
+        [tool.tox.env.a]
+        package = "skip"
+        commands = [[{ replace = "ref", env = "a", key = "list_dependencies_command", extend = true }]]
+
+This expands the Command's args into the command list, avoiding the need for string interpolation which doesn't work
+properly with Command values in TOML.
+
 Positional argument reference
 =============================
 

src/tox/config/loader/toml/_replace.py

@@ -20,6 +20,7 @@
     replace_env,
 )
 from tox.config.loader.stringify import stringify
+from tox.config.types import Command
 
 from ._validate import validate
 
@@ -117,7 +118,10 @@ def __call__(  # noqa: C901, PLR0912
 
     def _replace_ref(self, value: dict[str, TomlTypes], depth: int, *, skip_str: bool = False) -> TomlTypes:
         if self.conf is not None and (env := value.get("env")) and (key := value.get("key")):
-            return cast("TomlTypes", self.conf.get_env(cast("str", env))[cast("str", key)])
+            result = self.conf.get_env(cast("str", env))[cast("str", key)]
+            if isinstance(result, Command):
+                return cast("TomlTypes", result.args)
+            return cast("TomlTypes", result)
         if of := value.get("of"):
             validated_of = validate(of, list[str])
             loaded = self.loader.load_raw_from_root(self.loader.section.SEP.join(validated_of))

tests/config/source/test_toml_pyproject.py

@@ -979,3 +979,18 @@ def test_config_in_toml_handled_error_on_run(tox_project: ToxProjectCreator) ->
     assert "internal error" not in outcome.out
     assert "failed to load py.deps" in outcome.out
     assert "deps expected str, list[str], or list[Requirement]" in outcome.out
+
+
+def test_config_in_toml_replace_ref_command(tox_project: ToxProjectCreator) -> None:
+    project = tox_project({
+        "pyproject.toml": dedent("""
+        [tool.tox.env.a]
+        package = "skip"
+        commands = [[{ replace = "ref", env = "a", key = "list_dependencies_command", extend = true }]]
+        """),
+    })
+    outcome = project.run("c", "-e", "a", "-k", "commands")
+    outcome.assert_success()
+    assert "python" in outcome.out
+    assert "pip" in outcome.out
+    assert "freeze" in outcome.out