feat: Full shell completions for global and task argument in zsh and bash (#355)

Bumnp vesion to 0.41.0

- Requires reinstallation of completions scripts
- Backwards compatible with previous completion me
- Add testing harnesses for zsh and bash completion APIs
- Update compeletions installation docs
- Add testing README
- Fix some linting issues

Author: nat-n

.claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "hooks": {
+    "PostToolUse":
+    [
+      {
+        "matcher": "Edit|Write",
+        "hooks":
+        [
+          {
+            "type": "command",
+            "command": "poe format"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow":
+    [
+      "Bash(poe *)"
+    ]
+  }
+}

README.md

@@ -19,7 +19,7 @@
 
 - ✅ Tasks are run in poetry or uv's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)
 
-- ✅ [Shell completion of task names](https://poethepoet.natn.io/installation.html#shell-completion) (and global options too for zsh)
+- ✅ [Shell completion of task names and arguments](https://poethepoet.natn.io/installation.html#shell-completion)
 
 - ✅ The poe CLI can be used standalone, or as a [plugin for poetry](https://poethepoet.natn.io/poetry_plugin.html)
 

docs/index.rst

@@ -48,7 +48,7 @@ Top features
 
 |V| Tasks are run in poetry, or uv's virtualenv (or another env you specify)
 
-|V| :ref:`Shell completion of task names<shell_completion>` (and global options too for zsh)
+|V| :ref:`Shell completion of task names and arguments<shell_completion>`
 
 |V| The poe CLI can be used standalone, or as a :doc:`plugin for poetry<./poetry_plugin>`
 

docs/installation.rst

@@ -122,23 +122,47 @@ Zsh
   mkdir -p ~/.zfunc/
   poe _zsh_completion > ~/.zfunc/_poe
 
+Zsh completion includes:
+
+- Global CLI options (``-v``, ``-C``, etc.)
+- Task names with help text descriptions
+- Task-specific arguments (options and positional args)
+
 .. tip::
 
   You'll need to start a new shell for the new completion script to be loaded. If it still doesn't work try adding a call to :sh:`compinit` to the end of your zshrc file.
 
+  In some cases when upgrading to a newer version of the completion script it may be necessary to clean the zsh completions cache with `rm ~/.zcompdump*`
+
 Bash
 ~~~~
 
 .. code-block:: bash
 
-  # System bash
-  poe _bash_completion > /etc/bash_completion.d/poe.bash-completion
+  # Quick setup - add to ~/.bashrc
+  eval "$(poe _bash_completion)"
+
+  # Or install to a file (requires new shell to take effect):
+
+  # User local (recommended)
+  mkdir -p ~/.local/share/bash-completion/completions
+  poe _bash_completion > ~/.local/share/bash-completion/completions/poe
+
+  # System-wide
+  poe _bash_completion | sudo tee /etc/bash_completion.d/poe > /dev/null
 
   # Homebrew bash
-  poe _bash_completion > $(brew --prefix)/etc/bash_completion.d/poe.bash-completion
+  poe _bash_completion > $(brew --prefix)/etc/bash_completion.d/poe
+
+Bash completion includes:
 
+- Global CLI options (``-v``, ``-C``, etc.)
+- Task names
+- Task-specific arguments and choices
+
+.. tip::
 
-How to ensure installed bash completions are enabled may vary depending on your system.
+  If completions don't work after installing to a file, ensure you have the ``bash-completion`` package installed and that it's sourced in your ``~/.bashrc``. You may need to start a new shell session.
 
 Fish
 ~~~~

poethepoet/__init__.py

@@ -25,6 +25,16 @@ def main():
         raise SystemExit(result)
 
 
+def iter_tasks(target_path: str = "."):
+    from .config import PoeConfig
+
+    config = PoeConfig()
+    config.load_sync(target_path, strict=False)
+    for task in config.tasks.keys():
+        if task and task[0] != "_":
+            yield task
+
+
 def _run_builtin_task(
     task_name: str, second_arg: str = "", third_arg: str = ""
 ) -> bool:
@@ -45,6 +55,22 @@ def _run_builtin_task(
         _list_tasks(target_path=target_path)
         return True
 
+    if task_name == "_zsh_describe_tasks":
+        target_path = (
+            str(Path(second_arg).expanduser().resolve()) if second_arg else None
+        )
+        _zsh_describe_tasks(target_path=target_path)
+        return True
+
+    if task_name == "_describe_task_args":
+        # second_arg is task name, third_arg is optional target path
+        if second_arg:
+            target_path = (
+                str(Path(third_arg).expanduser().resolve()) if third_arg else None
+            )
+            _describe_task_args(task_name=second_arg, target_path=target_path)
+        return True
+
     target_path = ""
     if second_arg:
         if not second_arg.isalnum():
@@ -65,7 +91,7 @@ def _run_builtin_task(
     if task_name == "_bash_completion":
         from .completion.bash import get_bash_completion_script
 
-        print(get_bash_completion_script(name=second_arg, target_path=target_path))
+        print(get_bash_completion_script(name=second_arg))
         return True
 
     if task_name == "_fish_completion":
@@ -77,20 +103,160 @@ def _run_builtin_task(
     return False
 
 
+def _format_help(text: str | None, max_len: int = 60) -> str:
+    """
+    Format help text for shell completion output.
+
+    - Takes first line only
+    - Truncates with ellipsis if too long
+    - Escapes special characters (backslash, colon, tab)
+    """
+    if not text:
+        return " "  # Space placeholder - empty descriptions can confuse _describe
+    # First line only, strip whitespace
+    text = text.split("\n")[0].strip()
+
+    # Truncate with ellipsis if too long
+    if len(text) > max_len:
+        text = text[: max_len - 3].rstrip() + "..."
+
+    # Escape special characters for
+    return text.replace("\\", "\\\\").replace(":", "\\:").replace("\t", " ")
+
+
+def _escape_choice(value: str) -> str:
+    """
+    Escape a choice value for shell completion output.
+
+    Quotes the value with single quotes if it contains special characters
+    (spaces, tabs, newlines, quotes, backslash, $, backtick).
+    Single quotes within the value are escaped as '\\'' (end quote, escaped
+    quote, start quote).
+    """
+    if not value:
+        return value
+    # Characters that require quoting
+    if any(c in value for c in " \t\n\"'\\$`"):
+        # Escape single quotes: end quote, add escaped quote, start new quote
+        escaped = value.replace("'", "'\\''")
+        return f"'{escaped}'"
+    return value
+
+
 def _list_tasks(target_path: str | None = None):
     """
     A special task accessible via `poe _list_tasks` for use in shell completion
 
     Note this code path should include minimal imports to avoid slowing down the shell
     """
+    try:  # noqa: SIM105
+        print(" ".join(iter_tasks(target_path or "")))
+    except Exception:
+        # this happens if there's no pyproject.toml present
+        pass
+
 
+def _zsh_describe_tasks(target_path: str | None = None):
+    """
+    Output task names with descriptions in zsh _describe format.
+
+    Format: one task per line as "name:description"
+    - Colons in descriptions are escaped as \\:
+    - Descriptions truncated to 60 chars with ...
+    - Tasks without help get empty description (name:)
+    """
     try:
         from .config import PoeConfig
 
         config = PoeConfig()
         config.load_sync(target_path, strict=False)
-        task_names = (task for task in config.task_names if task and task[0] != "_")
-        print(" ".join(task_names))
+        tasks = config.tasks
+
+        for task_name in config.task_names:
+            if not task_name or task_name.startswith("_"):
+                continue
+
+            task_def = tasks.get(task_name, {})
+
+            # Extract help text - handle both dict and simple string task definitions
+            if isinstance(task_def, dict):
+                help_text = task_def.get("help", "") or ""
+            else:
+                help_text = ""
+
+            help_text = _format_help(help_text)
+            print(f"{task_name}:{help_text}")
+
     except Exception:
         # this happens if there's no pyproject.toml present
         pass
+
+
+def _describe_task_args(task_name: str, target_path: str | None = None):
+    """
+    Output argument specs for a specific task in a shell-agnostic format.
+
+    Used by both bash and zsh completion scripts.
+
+    Format: tab-separated fields per line:
+        <options>   <type>  <help>  <choices>
+
+    Where:
+    - options: comma-separated option strings (e.g., "--greeting,-g")
+    - type: "boolean", "string", "integer", "float", or "positional"
+    - help: description text (colons escaped as \\:)
+    - choices: space-separated list of allowed values ("_" if no choices)
+
+    Example output:
+        --greeting,-g   string  The greeting to use     _
+        --verbose,-v    boolean Verbose mode            _
+        --flavor,-f     string  Flavor                  vanilla chocolate strawberry
+        name    positional  The name argument           _
+    """
+    try:
+        from .config import PoeConfig
+        from .task.args import ArgSpec
+
+        config = PoeConfig()
+        config.load_sync(target_path, strict=False)
+
+        task_def = config.tasks.get(task_name, {})
+        if not isinstance(task_def, dict):
+            return
+
+        args_def = task_def.get("args")
+        if not args_def:
+            return
+
+        for arg in ArgSpec.normalize(args_def, strict=False):
+            help_text = _format_help(arg.get("help"))
+
+            # Format choices as space-separated values with proper escaping
+            # Use "_" as placeholder for empty (shell read may skip consecutive tabs)
+            choices_list = [
+                _escape_choice(str_choice)
+                for choice in (arg.get("choices") or [])
+                if (str_choice := str(choice))
+            ]
+            choices = " ".join(choices_list) if choices_list else "_"
+
+            arg_details: list[str] = []
+
+            if arg.get("positional"):
+                if name := arg.get("name", ""):
+                    arg_details = [name, "positional", help_text, choices]
+            else:
+                # Join all option strings for this arg
+                arg_details = [
+                    ",".join(arg.get("options")),
+                    arg.get("type", "string"),
+                    help_text,
+                    choices,
+                ]
+
+            if arg_details:
+                print("\t".join(arg_details))
+
+    except Exception:
+        # Silently fail - no completions is better than breaking the shell
+        pass

poethepoet/__version__.py

@@ -1 +1 @@
-__version__ = "0.40.0"
+__version__ = "0.41.0"