usecli 0.1.30__tar.gz → 0.1.32__tar.gz

{usecli-0.1.30 → usecli-0.1.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.30
+Version: 0.1.32
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>

{usecli-0.1.30 → usecli-0.1.32}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.30"
+version = "0.1.32"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]

{usecli-0.1.30 → usecli-0.1.32}/src/usecli/__init__.py

@@ -91,6 +91,20 @@ def _get_cli_help_text() -> str:
     return f"{display_name} - {display_description}"
 
 
+def _get_group_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
+def _build_alias_to_primary(alias_registry: dict[str, list[str]]) -> dict[str, str]:
+    alias_to_primary: dict[str, str] = {}
+    for primary, aliases in alias_registry.items():
+        alias_to_primary[primary] = primary
+        for alias in aliases:
+            alias_to_primary[alias] = primary
+    return alias_to_primary
+
+
 class PrefixMatchingGroup(TyperGroup):
     """Custom Typer group that supports prefix matching for commands.
 
@@ -111,12 +125,33 @@ class PrefixMatchingGroup(TyperGroup):
         if rv is not None:
             return rv
 
+        group_alias_registry = _get_group_alias_registry(app)
+        group_alias_to_primary = _build_alias_to_primary(group_alias_registry)
+
+        if (
+            cmd_name in group_alias_to_primary
+            and group_alias_to_primary[cmd_name] != cmd_name
+        ):
+            return TyperGroup.get_command(self, ctx, group_alias_to_primary[cmd_name])
+
         matches = [x for x in self.list_commands(ctx) if x.startswith(cmd_name)]
+        group_aliases = [
+            alias for aliases in group_alias_registry.values() for alias in aliases
+        ]
+        matches.extend([alias for alias in group_aliases if alias.startswith(cmd_name)])
+        matches = list(dict.fromkeys(matches))
 
         if not matches:
             return None
 
         if cmd_name in matches:
+            if (
+                cmd_name in group_alias_to_primary
+                and group_alias_to_primary[cmd_name] != cmd_name
+            ):
+                return TyperGroup.get_command(
+                    self, ctx, group_alias_to_primary[cmd_name]
+                )
             return TyperGroup.get_command(self, ctx, cmd_name)
 
         return FilteredListCommand(cmd_name)
@@ -192,7 +227,7 @@ def run_app(
     ),
     help: bool = typer.Option(None, "--help", "-h", is_eager=True),
     interactive: bool = typer.Option(
-        False, "--interactive", "-i", help="Run in interactive mode", is_eager=True
+        False, "--interactive", "-i", help="Run in interactive mode.", is_eager=True
     ),
 ) -> None:
     """Main callback for the CLI application.

{usecli-0.1.30 → usecli-0.1.32}/src/usecli/cli/commands/defaults/base/internal/fzf_command.py

@@ -155,11 +155,27 @@ def _run_fzf_menu(
         )
 
 
-def _get_group_subcommands(group_name: str) -> list[dict[str, Any]]:
+def _resolve_group_alias(app: typer.Typer, group_name: str) -> str:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    if not isinstance(registry, dict):
+        return group_name
+    for primary, aliases in registry.items():
+        if group_name == primary:
+            return primary
+        if group_name in aliases:
+            return primary
+    return group_name
+
+
+def _get_group_subcommands(
+    app: typer.Typer,
+    group_name: str,
+) -> list[dict[str, Any]]:
     from usecli.cli.core.base_command import NestedCommandRegistry
 
     registry = NestedCommandRegistry()
-    group_app = registry._groups.get(group_name)
+    resolved_group = _resolve_group_alias(app, group_name)
+    group_app = registry._groups.get(resolved_group)
 
     if not group_app:
         return []
@@ -260,12 +276,19 @@ def run_interactive(
         selected_cmd = next(
             (c for c in ordered_commands if c["name"] == cmd_name), None
         )
+        if not selected_cmd:
+            resolved_group = _resolve_group_alias(app, cmd_name)
+            if resolved_group != cmd_name:
+                cmd_name = resolved_group
+                selected_cmd = next(
+                    (c for c in ordered_commands if c["name"] == cmd_name), None
+                )
         if not selected_cmd:
             ErrorHandler.display_error(f"Unknown command '{cmd_name}'")
             raise typer.Exit(code=1)
 
     if selected_cmd and selected_cmd.get("is_group"):
-        subcommands = _get_group_subcommands(cmd_name)
+        subcommands = _get_group_subcommands(app, cmd_name)
         if not subcommands:
             ErrorHandler.display_error(f"No subcommands found for '{cmd_name}'")
             raise typer.Exit(code=1)

{usecli-0.1.30 → usecli-0.1.32}/src/usecli/cli/core/base_command.py

@@ -89,7 +89,7 @@ class NestedCommandRegistry:
                 False,
                 "--interactive",
                 "-i",
-                help="Run in interactive mode",
+                help="Run in interactive mode.",
             ),
         ) -> None:
             """Callback for the command group."""
@@ -182,7 +182,7 @@ class CustomHelpCommand(TyperCommand):
                 Option(
                     ["--interactive", "-i"],
                     is_flag=True,
-                    help="Run in interactive mode",
+                    help="Run in interactive mode.",
                 )
             )
 
@@ -314,6 +314,9 @@ class BaseCommand(ABC):
         """
         pass
 
+    def aliases(self) -> list[str]:
+        return []
+
     def visible(self) -> bool:
         return True
 
@@ -323,6 +326,7 @@ class BaseCommand(ABC):
 
         signature = self.signature()
         signature_parts = signature.split()
+        aliases = self.aliases()
 
         # Check if this is a space-separated nested command signature (e.g., "spec show")
         # vs a command with argument placeholders (e.g., "test-cmd <name>")
@@ -340,21 +344,173 @@ class BaseCommand(ABC):
             registry = NestedCommandRegistry()
             group_app = registry.get_or_create_group(self.app, group_name)
 
-            cmd_decorator = group_app.command(
+            normalized_aliases, group_aliases = self._normalize_nested_aliases(
+                primary_name=command_name,
+                aliases=aliases,
+                group_name=group_name,
+            )
+            self._register_with_aliases(
+                app=group_app,
                 name=command_name,
-                help=self.description(),
-                cls=CustomHelpCommand,
+                description=self.description(),
+                aliases=normalized_aliases,
+            )
+            self._register_group_aliases(
+                app=self.app,
+                group_name=group_name,
+                aliases=group_aliases,
             )
-            cmd_decorator(self.handle)
         else:
             # Single-level command (e.g., "help", "init", "config:set", "make:command")
             name = signature_parts[0]
-            cmd_decorator = self.app.command(
+            normalized_aliases = self._normalize_aliases(
+                primary_name=name,
+                aliases=aliases,
+                group_name=None,
+            )
+            self._register_with_aliases(
+                app=self.app,
                 name=name,
-                help=self.description(),
+                description=self.description(),
+                aliases=normalized_aliases,
+            )
+
+    def _register_with_aliases(
+        self,
+        app: typer.Typer,
+        name: str,
+        description: str,
+        aliases: list[str],
+    ) -> None:
+        cmd_decorator = app.command(
+            name=name,
+            help=description,
+            cls=CustomHelpCommand,
+        )
+        cmd_decorator(self.handle)
+
+        if not aliases:
+            return
+
+        alias_registry = self._get_alias_registry(app)
+        alias_registry.setdefault(name, [])
+        for alias in aliases:
+            if alias == name or alias in alias_registry[name]:
+                continue
+            alias_registry[name].append(alias)
+            alias_decorator = app.command(
+                name=alias,
+                help=description,
                 cls=CustomHelpCommand,
             )
-            cmd_decorator(self.handle)
+            alias_decorator(self.handle)
+
+    def _get_alias_registry(self, app: typer.Typer) -> dict[str, list[str]]:
+        if not hasattr(app, "_usecli_aliases"):
+            setattr(app, "_usecli_aliases", {})
+        registry = getattr(app, "_usecli_aliases")
+        if not isinstance(registry, dict):
+            registry = {}
+            setattr(app, "_usecli_aliases", registry)
+        return registry
+
+    def _get_group_alias_registry(self, app: typer.Typer) -> dict[str, list[str]]:
+        if not hasattr(app, "_usecli_group_aliases"):
+            setattr(app, "_usecli_group_aliases", {})
+        registry = getattr(app, "_usecli_group_aliases")
+        if not isinstance(registry, dict):
+            registry = {}
+            setattr(app, "_usecli_group_aliases", registry)
+        return registry
+
+    def _register_group_aliases(
+        self,
+        app: typer.Typer,
+        group_name: str,
+        aliases: list[str],
+    ) -> None:
+        if not aliases:
+            return
+
+        registry = self._get_group_alias_registry(app)
+        registry.setdefault(group_name, [])
+        for alias in aliases:
+            if alias == group_name or alias in registry[group_name]:
+                continue
+            registry[group_name].append(alias)
+
+    def _normalize_aliases(
+        self,
+        primary_name: str,
+        aliases: list[str],
+        group_name: str | None,
+    ) -> list[str]:
+        normalized: list[str] = []
+        for alias in aliases:
+            alias_parts = alias.split()
+            if group_name:
+                if len(alias_parts) == 2 and alias_parts[0] == group_name:
+                    alias_name = alias_parts[1]
+                elif len(alias_parts) == 1:
+                    alias_name = alias_parts[0]
+                else:
+                    continue
+                if not self._is_valid_subcommand_name(alias_name):
+                    continue
+            else:
+                if len(alias_parts) != 1:
+                    continue
+                alias_name = alias_parts[0]
+
+            if alias_name == primary_name or alias_name in normalized:
+                continue
+            normalized.append(alias_name)
+        return normalized
+
+    def _normalize_nested_aliases(
+        self,
+        primary_name: str,
+        aliases: list[str],
+        group_name: str,
+    ) -> tuple[list[str], list[str]]:
+        normalized: list[str] = []
+        group_aliases: list[str] = []
+
+        for alias in aliases:
+            alias_parts = alias.split()
+            if len(alias_parts) == 1:
+                alias_name = alias_parts[0]
+                if not self._is_valid_subcommand_name(alias_name):
+                    continue
+                if alias_name == primary_name or alias_name in normalized:
+                    continue
+                normalized.append(alias_name)
+                continue
+
+            if len(alias_parts) != 2:
+                continue
+
+            group_alias, alias_name = alias_parts
+
+            if not self._is_valid_subcommand_name(group_alias):
+                continue
+            if not self._is_valid_subcommand_name(alias_name):
+                continue
+
+            if group_alias == group_name:
+                if alias_name == primary_name or alias_name in normalized:
+                    continue
+                normalized.append(alias_name)
+                continue
+
+            if group_alias not in group_aliases:
+                group_aliases.append(group_alias)
+
+            if alias_name == primary_name or alias_name in normalized:
+                continue
+            normalized.append(alias_name)
+
+        return normalized, group_aliases
 
     def _is_valid_subcommand_name(self, name: str) -> bool:
         """Check if a string is a valid subcommand name (not an argument placeholder).

usecli-0.1.32/src/usecli/cli/core/ui/list.py

@@ -0,0 +1,362 @@
+"""Command listing utilities for usecli CLI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+import click
+import typer
+from rich.console import Console
+
+from usecli.cli.config.colors import COLOR
+from usecli.cli.core.ui.title import (
+    get_project_name,
+    get_script_command_name,
+    print_title,
+)
+
+if TYPE_CHECKING:
+    pass
+
+console = Console()
+
+SPACER_LENGTH = 6
+
+
+class CommandEntry(TypedDict):
+    name: str
+    display_name: str
+    help: str
+    aliases: list[str]
+
+
+class CommandMeta(TypedDict):
+    help: str
+    aliases: list[str]
+
+
+def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
+    """List all available commands with optional filtering.
+
+    Displays commands in a formatted list with sections for grouped commands
+    (those with colons in their names).
+
+    Args:
+        app: The Typer application instance.
+        prefix_filter: Optional prefix to filter commands by name.
+    """
+    project_name = get_project_name()
+    print_title(title=project_name)
+
+    click_group = typer.main.get_command(app)
+
+    alias_registry = _get_alias_registry(app)
+    alias_to_primary = _build_alias_to_primary(alias_registry)
+    group_alias_registry = _get_group_alias_registry(app)
+    group_alias_to_primary = _build_alias_to_primary(group_alias_registry)
+
+    command_name = get_script_command_name(default="usecli")
+
+    commands_by_name: dict[str, CommandMeta] = {}
+    for command in app.registered_commands:
+        callback = command.callback
+        name = command.name or (
+            getattr(callback, "__name__", "unknown") if callback else "unknown"
+        )
+        if name in alias_to_primary and alias_to_primary[name] != name:
+            continue
+        help_text = command.help or ""
+        if name not in commands_by_name or (
+            not commands_by_name[name]["help"] and help_text
+        ):
+            commands_by_name[name] = {
+                "help": help_text,
+                "aliases": alias_registry.get(name, list[str]()),
+            }
+
+    commands: list[CommandEntry] = []
+    for name in commands_by_name:
+        aliases = commands_by_name[name]["aliases"]
+        command_entry: CommandEntry = {
+            "name": name,
+            "display_name": _format_display_name(name, aliases),
+            "help": commands_by_name[name]["help"],
+            "aliases": aliases,
+        }
+        commands.append(command_entry)
+    commands.sort(key=lambda x: x["name"])
+
+    groups: dict[str, str] = {}
+    if isinstance(click_group, click.Group):
+        for cmd_name, cmd_obj in click_group.commands.items():
+            if isinstance(cmd_obj, click.Group):
+                if (
+                    cmd_name in group_alias_to_primary
+                    and group_alias_to_primary[cmd_name] != cmd_name
+                ):
+                    continue
+                groups[cmd_name] = (
+                    getattr(cmd_obj, "help", f"Commands for {cmd_name}")
+                    or f"Commands for {cmd_name}"
+                )
+
+    option_flags = []
+    display_params = _order_completion_params(click_group.params or [])
+    if display_params:
+        for param in display_params:
+            flags = ", ".join(param.opts)
+            if "--help" in flags:
+                continue
+            option_flags.append(flags)
+
+    help_flags = "--help, -h"
+    all_option_flags = [help_flags] + option_flags
+    group_entries: list[CommandEntry] = []
+    for group_name, group_help in groups.items():
+        aliases = group_alias_registry.get(group_name, list[str]())
+        group_entries.append(
+            {
+                "name": group_name,
+                "display_name": _format_display_name(group_name, aliases),
+                "help": group_help,
+                "aliases": aliases,
+            }
+        )
+
+    if prefix_filter:
+        filtered = [
+            c
+            for c in commands
+            if c["name"].startswith(prefix_filter)
+            or any(alias.startswith(prefix_filter) for alias in c["aliases"])
+        ]
+        filtered_groups = [
+            g
+            for g in group_entries
+            if g["name"].startswith(prefix_filter)
+            or any(alias.startswith(prefix_filter) for alias in g["aliases"])
+        ]
+        if not filtered and not filtered_groups:
+            console.print(f"  [dim]No commands found for '{prefix_filter}'[/dim]")
+            console.print()
+            return
+        commands = filtered
+        group_entries = filtered_groups
+
+    all_display_names = [cmd["display_name"] for cmd in commands] + [
+        entry["display_name"] for entry in group_entries
+    ]
+    all_labels = all_display_names + all_option_flags
+    longest_label_length = max((len(label) for label in all_labels), default=0)
+
+    console.print(f"[bold {COLOR.SECONDARY}]Usage:[/bold {COLOR.SECONDARY}]")
+    console.print(f"  [{COLOR.PRIMARY}]{command_name} [OPTIONS] [ARGUMENTS]")
+    console.print()
+
+    console.print(f"[bold {COLOR.SECONDARY}]Options:")
+
+    help_padding = " " * (longest_label_length - len(help_flags) + SPACER_LENGTH)
+    console.print(
+        f"  [{COLOR.OPTION}]{help_flags}[/{COLOR.OPTION}]{help_padding}Show this message and exit."
+    )
+
+    if display_params:
+        for param in display_params:
+            flags = ", ".join(param.opts)
+            if "--help" in flags:
+                continue
+            description = _get_option_description(param)
+            padding = " " * (longest_label_length - len(flags) + SPACER_LENGTH)
+            console.print(
+                f"  [{COLOR.OPTION}]{flags}[/{COLOR.OPTION}]{padding}{description}"
+            )
+    console.print()
+
+    if not prefix_filter:
+        console.print(f"[bold {COLOR.SECONDARY}]Available commands:")
+
+    group_names = set(groups.keys())
+    top_level: list[CommandEntry] = [
+        c for c in commands if ":" not in c["name"] and c["name"] not in group_names
+    ]
+    with_colon: list[CommandEntry] = [c for c in commands if ":" in c["name"]]
+
+    def print_command(cmd: CommandEntry) -> None:
+        """Print a single command with proper formatting."""
+        display_name = cmd["display_name"]
+        padding = " " * (longest_label_length - len(display_name) + SPACER_LENGTH)
+        console.print(
+            f"  [{COLOR.COMMAND} not bold]{display_name}[/{COLOR.COMMAND} not bold]{padding}{cmd['help']}"
+        )
+
+    top_level.extend(group_entries)
+
+    top_level.sort(key=lambda x: x["name"])
+
+    if top_level:
+        for cmd in top_level:
+            print_command(cmd)
+        console.print()
+
+    sections: dict[str, list[CommandEntry]] = {}
+    for cmd in with_colon:
+        section_prefix = cmd["name"].split(":")[0]
+        if section_prefix not in sections:
+            sections[section_prefix] = []
+        sections[section_prefix].append(cmd)
+
+    for section_prefix, section_cmds in sections.items():
+        console.print(f"[bold {COLOR.SECONDARY}]{section_prefix}:")
+        for cmd in section_cmds:
+            print_command(cmd)
+        console.print()
+
+
+def list_group_commands(group_app: typer.Typer, group_name: str) -> None:
+    """List all commands within a specific command group.
+
+    Displays commands in a formatted list for a nested command group,
+    similar to how list_commands works for the main app.
+
+    Args:
+        group_app: The Typer sub-app for the command group.
+        group_name: The name of the command group.
+    """
+    alias_registry = _get_alias_registry(group_app)
+    alias_to_primary = _build_alias_to_primary(alias_registry)
+
+    command_name = get_script_command_name(default="usecli")
+
+    console.print(f"[bold {COLOR.SECONDARY}]Usage:[/bold {COLOR.SECONDARY}]")
+    console.print(
+        f"  [{COLOR.PRIMARY}]{command_name} {group_name} [COMMAND] [OPTIONS][/]"
+    )
+    console.print()
+    commands_by_name: dict[str, CommandMeta] = {}
+    for command in group_app.registered_commands:
+        callback = command.callback
+        name = command.name or (
+            getattr(callback, "__name__", "unknown") if callback else "unknown"
+        )
+        if name in alias_to_primary and alias_to_primary[name] != name:
+            continue
+        help_text = command.help or ""
+        if name not in commands_by_name or (
+            not commands_by_name[name]["help"] and help_text
+        ):
+            commands_by_name[name] = {
+                "help": help_text,
+                "aliases": alias_registry.get(name, list[str]()),
+            }
+
+    commands: list[CommandEntry] = []
+    for name in commands_by_name:
+        aliases = commands_by_name[name]["aliases"]
+        command_entry: CommandEntry = {
+            "name": name,
+            "display_name": _format_display_name(name, aliases),
+            "help": commands_by_name[name]["help"],
+            "aliases": aliases,
+        }
+        commands.append(command_entry)
+    commands.sort(key=lambda x: x["name"])
+
+    click_group = typer.main.get_command(group_app)
+    option_flags = []
+    display_params = _order_completion_params(click_group.params or [])
+    if display_params:
+        for param in display_params:
+            flags = ", ".join(param.opts)
+            if "--help" in flags:
+                continue
+            option_flags.append(flags)
+
+    help_flags = "--help, -h"
+    all_option_flags = [help_flags] + option_flags
+    all_display_names = [cmd["display_name"] for cmd in commands]
+    all_labels = all_display_names + all_option_flags
+    longest_label_length = max((len(label) for label in all_labels), default=0)
+
+    console.print(f"[bold {COLOR.SECONDARY}]Options:")
+    help_padding = " " * (longest_label_length - len(help_flags) + SPACER_LENGTH)
+    console.print(
+        f"  [{COLOR.OPTION}]{help_flags}[/{COLOR.OPTION}]{help_padding}Show this message and exit."
+    )
+
+    if display_params:
+        for param in display_params:
+            flags = ", ".join(param.opts)
+            if "--help" in flags:
+                continue
+            description = _get_option_description(param)
+            padding = " " * (longest_label_length - len(flags) + SPACER_LENGTH)
+            console.print(
+                f"  [{COLOR.OPTION}]{flags}[/{COLOR.OPTION}]{padding}{description}"
+            )
+    console.print()
+
+    console.print(f"[bold {COLOR.SECONDARY}]Available commands:")
+
+    for cmd in commands:
+        display_name = cmd["display_name"]
+        padding = " " * (longest_label_length - len(display_name) + SPACER_LENGTH)
+        console.print(
+            f"  [{COLOR.COMMAND}]{display_name}[/{COLOR.COMMAND}]{padding}{cmd['help']}"
+        )
+
+    console.print()
+
+
+def _get_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
+def _get_group_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
+def _get_option_description(param: click.Parameter) -> str:
+    if "--show-completion" in param.opts:
+        return "Show completion for the current shell."
+    return getattr(param, "help", "") or ""
+
+
+def _order_completion_params(
+    params: list[click.Parameter],
+) -> list[click.Parameter]:
+    ordered = list(params)
+    install_index = None
+    show_index = None
+    for index, param in enumerate(ordered):
+        opts = set(param.opts)
+        if "--install-completion" in opts:
+            install_index = index
+        if "--show-completion" in opts:
+            show_index = index
+    if install_index is None or show_index is None:
+        return ordered
+    if install_index < show_index:
+        show_param = ordered.pop(show_index)
+        ordered.insert(install_index, show_param)
+        return ordered
+    if show_index < install_index:
+        install_param = ordered.pop(install_index)
+        ordered.insert(show_index, install_param)
+    return ordered
+
+
+def _build_alias_to_primary(alias_registry: dict[str, list[str]]) -> dict[str, str]:
+    alias_to_primary: dict[str, str] = {}
+    for primary, aliases in alias_registry.items():
+        alias_to_primary[primary] = primary
+        for alias in aliases:
+            alias_to_primary[alias] = primary
+    return alias_to_primary
+
+
+def _format_display_name(name: str, aliases: list[str]) -> str:
+    if not aliases:
+        return name
+    return f"{name}, {', '.join(aliases)}"

{usecli-0.1.30 → usecli-0.1.32}/src/usecli/cli/templates/command.py.j2

@@ -12,6 +12,9 @@ class {{ class_name }}(BaseCommand):
     def description(self) -> str:
         return "Description for {{ command_name }} command"
 
+    # def aliases(self) -> list[str]:
+    #    return [{{ command_name[:3] }}]
+
     def handle(
         self,
         name: str = Argument(..., help="An example argument"),

usecli-0.1.30/src/usecli/cli/core/ui/list.py

@@ -1,217 +0,0 @@
-"""Command listing utilities for usecli CLI."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import click
-import typer
-from rich.console import Console
-
-from usecli.cli.config.colors import COLOR
-from usecli.cli.core.ui.title import (
-    get_project_name,
-    get_script_command_name,
-    print_title,
-)
-
-if TYPE_CHECKING:
-    pass
-
-console = Console()
-
-SPACER_LENGTH = 18
-
-
-def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
-    """List all available commands with optional filtering.
-
-    Displays commands in a formatted list with sections for grouped commands
-    (those with colons in their names).
-
-    Args:
-        app: The Typer application instance.
-        prefix_filter: Optional prefix to filter commands by name.
-    """
-    project_name = get_project_name()
-    print_title(title=project_name)
-
-    click_group = typer.main.get_command(app)
-
-    all_command_names = list({cmd.name for cmd in app.registered_commands if cmd.name})
-    longest_name_length = (
-        max(len(name) for name in all_command_names) if all_command_names else 0
-    )
-
-    command_name = get_script_command_name(default="usecli")
-
-    console.print(f"[bold {COLOR.SECONDARY}]Usage:[/bold {COLOR.SECONDARY}]")
-    console.print(f"  [{COLOR.PRIMARY}]{command_name} [OPTIONS] [ARGUMENTS]")
-    console.print()
-
-    console.print(f"[bold {COLOR.SECONDARY}]Options:")
-
-    help_flags = "--help, -h"
-    help_padding = " " * (longest_name_length - len(help_flags) + SPACER_LENGTH)
-    console.print(
-        f"  [{COLOR.OPTION}]{help_flags}[/{COLOR.OPTION}]{help_padding}Show this message and exit."
-    )
-
-    if click_group.params:
-        for param in click_group.params:
-            flags = ", ".join(param.opts)
-            if "--help" in flags:
-                continue
-            description = getattr(param, "help", "") or ""
-            padding = " " * (longest_name_length - len(flags) + SPACER_LENGTH)
-            console.print(
-                f"  [{COLOR.OPTION}]{flags}[/{COLOR.OPTION}]{padding}{description}"
-            )
-    console.print()
-
-    commands_by_name: dict[str, str] = {}
-    for command in app.registered_commands:
-        callback = command.callback
-        name = command.name or (
-            getattr(callback, "__name__", "unknown") if callback else "unknown"
-        )
-        help_text = command.help or ""
-        if name not in commands_by_name or (not commands_by_name[name] and help_text):
-            commands_by_name[name] = help_text
-
-    commands = [
-        {"name": name, "help": help_text}
-        for name, help_text in commands_by_name.items()
-    ]
-    commands.sort(key=lambda x: x["name"])
-
-    if prefix_filter:
-        filtered = [c for c in commands if c["name"].startswith(prefix_filter)]
-        if not filtered:
-            console.print(f"  [dim]No commands found for '{prefix_filter}'[/dim]")
-            console.print()
-            return
-        commands = filtered
-
-    if not prefix_filter:
-        console.print(f"[bold {COLOR.SECONDARY}]Available commands:")
-
-    groups: dict[str, str] = {}
-    if isinstance(click_group, click.Group):
-        for cmd_name, cmd_obj in click_group.commands.items():
-            if isinstance(cmd_obj, click.Group):
-                groups[cmd_name] = (
-                    getattr(cmd_obj, "help", f"Commands for {cmd_name}")
-                    or f"Commands for {cmd_name}"
-                )
-
-    top_level = [
-        c for c in commands if ":" not in c["name"] and c["name"] not in groups
-    ]
-    with_colon = [c for c in commands if ":" in c["name"]]
-
-    all_names = all_command_names + list(groups.keys())
-    if all_names:
-        longest_name_length = max(len(name) for name in all_names)
-
-    def print_command(cmd: dict[str, str]) -> None:
-        """Print a single command with proper formatting."""
-        padding = " " * (longest_name_length - len(cmd["name"]) + SPACER_LENGTH)
-        console.print(
-            f"  [{COLOR.COMMAND} not bold]{cmd['name']}[/{COLOR.COMMAND} not bold]{padding}{cmd['help']}"
-        )
-
-    for group_name, group_help in groups.items():
-        top_level.append({"name": group_name, "help": group_help})
-
-    top_level.sort(key=lambda x: x["name"])
-
-    if top_level:
-        for cmd in top_level:
-            print_command(cmd)
-        console.print()
-
-    sections: dict[str, list[dict[str, str]]] = {}
-    for cmd in with_colon:
-        section_prefix = cmd["name"].split(":")[0]
-        if section_prefix not in sections:
-            sections[section_prefix] = []
-        sections[section_prefix].append(cmd)
-
-    for section_prefix, section_cmds in sections.items():
-        console.print(f"[bold {COLOR.SECONDARY}]{section_prefix}:")
-        for cmd in section_cmds:
-            print_command(cmd)
-        console.print()
-
-
-def list_group_commands(group_app: typer.Typer, group_name: str) -> None:
-    """List all commands within a specific command group.
-
-    Displays commands in a formatted list for a nested command group,
-    similar to how list_commands works for the main app.
-
-    Args:
-        group_app: The Typer sub-app for the command group.
-        group_name: The name of the command group.
-    """
-    all_command_names = list(
-        {cmd.name for cmd in group_app.registered_commands if cmd.name}
-    )
-    longest_name_length = (
-        max(len(name) for name in all_command_names) if all_command_names else 0
-    )
-
-    command_name = get_script_command_name(default="usecli")
-
-    console.print(f"[bold {COLOR.SECONDARY}]Usage:[/bold {COLOR.SECONDARY}]")
-    console.print(
-        f"  [{COLOR.PRIMARY}]{command_name} {group_name} [COMMAND] [OPTIONS][/]"
-    )
-    console.print()
-
-    console.print(f"[bold {COLOR.SECONDARY}]Options:")
-    help_flags = "--help, -h"
-    help_padding = " " * (longest_name_length - len(help_flags) + SPACER_LENGTH)
-    console.print(
-        f"  [{COLOR.OPTION}]{help_flags}[/{COLOR.OPTION}]{help_padding}Show this message and exit."
-    )
-
-    click_group = typer.main.get_command(group_app)
-    if click_group.params:
-        for param in click_group.params:
-            flags = ", ".join(param.opts)
-            if "--help" in flags:
-                continue
-            description = getattr(param, "help", "") or ""
-            padding = " " * (longest_name_length - len(flags) + SPACER_LENGTH)
-            console.print(
-                f"  [{COLOR.OPTION}]{flags}[/{COLOR.OPTION}]{padding}{description}"
-            )
-    console.print()
-
-    commands_by_name: dict[str, str] = {}
-    for command in group_app.registered_commands:
-        callback = command.callback
-        name = command.name or (
-            getattr(callback, "__name__", "unknown") if callback else "unknown"
-        )
-        help_text = command.help or ""
-        if name not in commands_by_name or (not commands_by_name[name] and help_text):
-            commands_by_name[name] = help_text
-
-    commands = [
-        {"name": name, "help": help_text}
-        for name, help_text in commands_by_name.items()
-    ]
-    commands.sort(key=lambda x: x["name"])
-
-    console.print(f"[bold {COLOR.SECONDARY}]Available commands:")
-
-    for cmd in commands:
-        padding = " " * (longest_name_length - len(cmd["name"]) + SPACER_LENGTH)
-        console.print(
-            f"  [{COLOR.COMMAND}]{cmd['name']}[/{COLOR.COMMAND}]{padding}{cmd['help']}"
-        )
-
-    console.print()