Note when commands & tasks accept extra args.

This completes the `-l` / `--list` output needed to allow command-line
exploration of a project's dev setup.

CHANGES.md

@@ -1,5 +1,9 @@
 # Release Notes
 
+## 0.16.0
+
+Note when commands and tasks can accept extra args in `-l` / `--list` output.
+
 ## 0.15.0
 
 Add support for hiding commands and tasks from `-l` / `--list` output.

dev_cmd/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2024 John Sirois.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"

dev_cmd/model.py

@@ -54,7 +54,7 @@ class Task:
     hidden: bool = False
     description: str | None = None
 
-    def accepts_extra_args(self, skips: Container[str]) -> Command | None:
+    def accepts_extra_args(self, skips: Container[str] = ()) -> Command | None:
         if self.name in skips:
             return None
         return self.steps.accepts_extra_args(skips)

dev_cmd/run.py

@@ -279,8 +279,14 @@ def _list(
         if command.hidden:
             continue
         rendered_command_name = color.color(command.name, fg="magenta", style="bold")
+        if command.accepts_extra_args:
+            extra_args_help = color.magenta(f" (-- extra {command.args[0]} args ...)")
+            rendered_command_name = f"{rendered_command_name}{extra_args_help}"
         if command.description:
-            console.print(f"{rendered_command_name}: {color.color(command.description, fg='gray')}")
+            console.print(f"{rendered_command_name}:")
+            console.print(f"    {color.color(command.description, fg='gray')}")
+        elif command.factor_descriptions:
+            console.print(f"{rendered_command_name}:")
         else:
             console.print(rendered_command_name)
         for factor_description in command.factor_descriptions:
@@ -318,8 +324,12 @@ def _list(
             if task.hidden:
                 continue
             rendered_task_name = color.color(task.name, fg="magenta", style="bold")
+            if extra_args_cmd := task.accepts_extra_args():
+                extra_args_help = color.magenta(f" (-- extra {extra_args_cmd.args[0]} args ...)")
+                rendered_task_name = f"{rendered_task_name}{extra_args_help}"
             if task.description:
-                console.print(f"{rendered_task_name}: {color.color(task.description, fg='gray')}")
+                console.print(f"{rendered_task_name}: ")
+                console.print(f"    {color.color(task.description, fg='gray')}")
             else:
                 console.print(rendered_task_name)