Formalize cli shortcuts and customize cli help

Author: davegaeddert

plain-code/plain/code/cli.py

@@ -119,7 +119,7 @@ def maybe_exit(return_code: int) -> None:
 
 
 @without_runtime_setup
-@register_cli("fix")
+@register_cli("fix", shortcut_for="code")
 @cli.command()
 @click.pass_context
 @click.argument("path", default=".")

plain-models/plain/models/backups/cli.py

@@ -11,7 +11,7 @@
 from .core import DatabaseBackups
 
 
-@register_cli("backups")
+@register_cli("backups", shortcut_for="models")
 @click.group("backups")
 def cli() -> None:
     """Local database backups"""

plain-models/plain/models/cli.py

@@ -136,7 +136,7 @@ def list_models(package_labels: tuple[str, ...], app_only: bool) -> None:
         click.echo(f"  package: {pkg_name}\n")
 
 
-@register_cli("makemigrations")
+@register_cli("makemigrations", shortcut_for="models")
 @cli.command()
 @click.argument("package_labels", nargs=-1)
 @click.option(
@@ -341,7 +341,7 @@ def write_migration_files(
         write_migration_files(changes)
 
 
-@register_cli("migrate")
+@register_cli("migrate", shortcut_for="models")
 @cli.command()
 @click.argument("package_label", required=False)
 @click.argument("migration_name", required=False)

plain/plain/cli/core.py

@@ -140,5 +140,51 @@ def list_commands(self, ctx: Context) -> list[str]:
         self._ensure_registry_loaded()
         return super().list_commands(ctx)
 
+    def format_commands(self, ctx: Context, formatter: Any) -> None:
+        """Format commands with separate sections for shortcuts and regular commands."""
+        self._ensure_registry_loaded()
+
+        # Get all commands from both sources
+        commands = []
+        for source in self.sources:
+            for name in source.list_commands(ctx):
+                cmd = source.get_command(ctx, name)
+                if cmd is not None:
+                    commands.append((name, cmd))
+
+        if not commands:
+            return
+
+        # Get metadata about shortcuts from the registry
+        shortcuts_metadata = cli_registry.get_shortcuts()
+
+        # Separate shortcuts from regular commands
+        shortcuts = []
+        regular_commands = []
+
+        for name, cmd in commands:
+            if name in shortcuts_metadata:
+                # This is a shortcut
+                help_text = cmd.get_short_help_str(limit=200)
+                shortcut_for = shortcuts_metadata[name].shortcut_for
+                if shortcut_for:
+                    # Add italic styling to the alias information (more concise)
+                    alias_info = click.style(f"(→ {shortcut_for})", italic=True)
+                    help_text = f"{help_text} {alias_info}"
+                shortcuts.append((name, help_text))
+            else:
+                # Regular command or group
+                regular_commands.append((name, cmd.get_short_help_str(limit=200)))
+
+        # Write shortcuts section if any exist
+        if shortcuts:
+            with formatter.section("Shortcuts"):
+                formatter.write_dl(sorted(shortcuts))
+
+        # Write regular commands section
+        if regular_commands:
+            with formatter.section("Commands"):
+                formatter.write_dl(sorted(regular_commands))
+
 
 cli = PlainCommandCollection()

plain/plain/cli/formatting.py

@@ -19,7 +19,7 @@ def write_usage(self, prog: str, args: str = "", prefix: str = "Usage: ") -> Non
     def write_dl(
         self,
         rows: list[tuple[str, str]],
-        col_max: int = 30,
+        col_max: int = 20,
         col_spacing: int = 2,
     ) -> None:
         """Writes a definition list into the buffer.  This is how options
@@ -54,10 +54,15 @@ def write_dl(
             lines = wrapped_text.splitlines()
 
             if lines:
-                self.write(f"{lines[0]}\n")
+                # Dim the description text
+                first_line_styled = click.style(lines[0], dim=True)
+                self.write(f"{first_line_styled}\n")
 
                 for line in lines[1:]:
-                    self.write(f"{'':>{first_col + self.current_indent}}{line}\n")
+                    line_styled = click.style(line, dim=True)
+                    self.write(
+                        f"{'':>{first_col + self.current_indent}}{line_styled}\n"
+                    )
             else:
                 self.write("\n")
 
@@ -66,6 +71,11 @@ class PlainContext(click.Context):
     formatter_class = PlainHelpFormatter
 
     def __init__(self, *args: Any, **kwargs: Any):
+        # Set a wider max_content_width for help text (default is 80)
+        # This allows descriptions to fit more comfortably on one line
+        if "max_content_width" not in kwargs:
+            kwargs["max_content_width"] = 140
+
         super().__init__(*args, **kwargs)
 
         # Force colors in CI environments

plain/plain/cli/registry.py

@@ -1,19 +1,33 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, NamedTuple
 
 from plain.packages import packages_registry
 
 
+class CommandMetadata(NamedTuple):
+    """Metadata about a registered command."""
+
+    cmd: Any
+    shortcut_for: str | None = None
+
+
 class CLIRegistry:
-    def __init__(self):
-        self._commands: dict[str, Any] = {}
+    def __init__(self) -> None:
+        self._commands: dict[str, CommandMetadata] = {}
 
-    def register_command(self, cmd: Any, name: str) -> None:
+    def register_command(
+        self, cmd: Any, name: str, shortcut_for: str | None = None
+    ) -> None:
         """
         Register a CLI command or group with the specified name.
+
+        Args:
+            cmd: The click command or group to register
+            name: The name to register the command under
+            shortcut_for: Optional parent command this is a shortcut for (e.g., "models" for migrate)
         """
-        self._commands[name] = cmd
+        self._commands[name] = CommandMetadata(cmd=cmd, shortcut_for=shortcut_for)
 
     def import_modules(self) -> None:
         """
@@ -23,27 +37,66 @@ def import_modules(self) -> None:
 
     def get_commands(self) -> dict[str, Any]:
         """
-        Get all registered commands.
+        Get all registered commands (just the command objects, not metadata).
+        """
+        return {name: metadata.cmd for name, metadata in self._commands.items()}
+
+    def get_commands_with_metadata(self) -> dict[str, CommandMetadata]:
+        """
+        Get all registered commands with their metadata.
         """
         return self._commands
 
+    def get_shortcuts(self) -> dict[str, CommandMetadata]:
+        """
+        Get only commands that are shortcuts.
+        """
+        return {
+            name: metadata
+            for name, metadata in self._commands.items()
+            if metadata.shortcut_for
+        }
+
+    def get_regular_commands(self) -> dict[str, CommandMetadata]:
+        """
+        Get only commands that are not shortcuts.
+        """
+        return {
+            name: metadata
+            for name, metadata in self._commands.items()
+            if not metadata.shortcut_for
+        }
+
 
 cli_registry = CLIRegistry()
 
 
-def register_cli(name: str) -> Any:
+def register_cli(name: str, shortcut_for: str | None = None) -> Any:
     """
     Register a CLI command or group with the given name.
 
+    Args:
+        name: The name to register the command under
+        shortcut_for: Optional parent command this is a shortcut for.
+                     For example, @register_cli("migrate", shortcut_for="models")
+                     indicates that "plain migrate" is a shortcut for "plain models migrate"
+
     Usage:
+        # Register a regular command group
         @register_cli("users")
         @click.group()
         def users_cli():
             pass
+
+        # Register a shortcut command
+        @register_cli("migrate", shortcut_for="models")
+        @click.command()
+        def migrate():
+            pass
     """
 
     def wrapper(cmd: Any) -> Any:
-        cli_registry.register_command(cmd, name)
+        cli_registry.register_command(cmd, name, shortcut_for=shortcut_for)
         return cmd
 
     return wrapper