Common commands, core commands

Author: davegaeddert

example/app/cli.py

@@ -0,0 +1,26 @@
+import sys
+
+import click
+
+from plain.cli import register_cli
+
+from .users.models import User
+
+
+@register_cli("app")
+@click.group()
+def cli():
+    """App related commands"""
+    pass
+
+
+@cli.command()
+@click.argument("email")
+def enable_admin_user(email):
+    """Enable admin privileges for a user."""
+    result = User.query.filter(email=email).update(is_admin=True)
+    if result:
+        click.echo(f"User {email} is now an admin.")
+    else:
+        click.echo(f"No user found with email {email}.")
+        sys.exit(1)

plain-code/plain/code/cli.py

@@ -10,7 +10,7 @@
 
 from plain.cli import register_cli
 from plain.cli.print import print_event
-from plain.cli.runtime import without_runtime_setup
+from plain.cli.runtime import common_command, without_runtime_setup
 
 from .biome import Biome
 
@@ -118,6 +118,7 @@ def maybe_exit(return_code: int) -> None:
         maybe_exit(result.returncode)
 
 
+@common_command
 @without_runtime_setup
 @register_cli("fix", shortcut_for="code")
 @cli.command()

plain-dev/plain/dev/cli.py

@@ -8,6 +8,7 @@
 import click
 
 from plain.cli import register_cli
+from plain.cli.runtime import common_command
 from plain.runtime import APP_PATH, PLAIN_TEMP_PATH
 
 from .alias import AliasManager
@@ -80,6 +81,7 @@ def _auto_start_services() -> None:
             sys.exit(1)
 
 
+@common_command
 @register_cli("dev")
 @click.group(cls=DevGroup, invoke_without_command=True)
 @click.pass_context

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

@@ -7,10 +7,12 @@
 import click
 
 from plain.cli import register_cli
+from plain.cli.runtime import common_command
 
 from .core import DatabaseBackups
 
 
+@common_command
 @register_cli("backups", shortcut_for="models")
 @click.group("backups")
 def cli() -> None:

plain-models/plain/models/cli.py

@@ -9,6 +9,7 @@
 import click
 
 from plain.cli import register_cli
+from plain.cli.runtime import common_command
 from plain.packages import packages_registry
 from plain.runtime import settings
 from plain.utils.text import Truncator
@@ -136,6 +137,7 @@ def list_models(package_labels: tuple[str, ...], app_only: bool) -> None:
         click.echo(f"  package: {pkg_name}\n")
 
 
+@common_command
 @register_cli("makemigrations", shortcut_for="models")
 @cli.command()
 @click.argument("package_labels", nargs=-1)
@@ -341,6 +343,7 @@ def write_migration_files(
         write_migration_files(changes)
 
 
+@common_command
 @register_cli("migrate", shortcut_for="models")
 @cli.command()
 @click.argument("package_label", required=False)

plain-pytest/plain/pytest/cli.py

@@ -6,8 +6,10 @@
 from dotenv import load_dotenv
 
 from plain.cli import register_cli
+from plain.cli.runtime import common_command
 
 
+@common_command
 @register_cli("test")
 @click.command(
     context_settings={

plain/plain/cli/__init__.py

@@ -1,3 +1,4 @@
 from .registry import register_cli
+from .runtime import common_command
 
-__all__ = ["register_cli"]
+__all__ = ["register_cli", "common_command"]

plain/plain/cli/build.py

@@ -9,8 +9,10 @@
 
 import plain.runtime
 from plain.assets.compile import compile_assets, get_compiled_path
+from plain.cli.runtime import common_command
 
 
+@common_command
 @click.command()
 @click.option(
     "--keep-original/--no-keep-original",

plain/plain/cli/core.py

@@ -141,50 +141,65 @@ def list_commands(self, ctx: Context) -> list[str]:
         return super().list_commands(ctx)
 
     def format_commands(self, ctx: Context, formatter: Any) -> None:
-        """Format commands with separate sections for shortcuts and regular commands."""
+        """Format commands with separate sections for common, core, and package commands."""
         self._ensure_registry_loaded()
 
-        # Get all commands from both sources
+        # Get all commands from both sources, tracking their source
         commands = []
-        for source in self.sources:
+        for source_index, source in enumerate(self.sources):
             for name in source.list_commands(ctx):
                 cmd = source.get_command(ctx, name)
                 if cmd is not None:
-                    commands.append((name, cmd))
+                    # source_index 0 = plain_cli (core), 1+ = registry (packages)
+                    commands.append((name, cmd, source_index))
 
         if not commands:
             return
 
-        # Get metadata about shortcuts from the registry
+        # Get metadata from the registry (for shortcuts)
         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))
+        # Separate commands into common, core, and package
+        common_commands = []
+        core_commands = []
+        package_commands = []
+
+        for name, cmd, source_index in commands:
+            help_text = cmd.get_short_help_str(limit=200)
+
+            # Check if command is marked as common via decorator
+            is_common = getattr(cmd, "is_common_command", False)
+
+            if is_common:
+                # This is a common command
+                # Add arrow notation if it's also a shortcut
+                if name in shortcuts_metadata:
+                    shortcut_for = shortcuts_metadata[name].shortcut_for
+                    if shortcut_for:
+                        alias_info = click.style(f"(→ {shortcut_for})", italic=True)
+                        help_text = f"{help_text} {alias_info}"
+                common_commands.append((name, help_text))
+            elif source_index == 0:
+                # Package command (from registry, inserted at index 0)
+                package_commands.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))
+                # Core command (from plain_cli, at index 1)
+                core_commands.append((name, help_text))
+
+        # Write common commands section if any exist
+        if common_commands:
+            with formatter.section("Common Commands"):
+                formatter.write_dl(sorted(common_commands))
+
+        # Write core commands section if any exist
+        if core_commands:
+            with formatter.section("Core Commands"):
+                formatter.write_dl(sorted(core_commands))
+
+        # Write package commands section if any exist
+        if package_commands:
+            with formatter.section("Package Commands"):
+                formatter.write_dl(sorted(package_commands))
 
 
 cli = PlainCommandCollection()

plain/plain/cli/formatting.py

@@ -9,7 +9,7 @@
 
 class PlainHelpFormatter(click.HelpFormatter):
     def write_heading(self, heading: str) -> None:
-        styled_heading = click.style(heading, underline=True)
+        styled_heading = click.style(heading, dim=True)
         self.write(f"{'':>{self.current_indent}}{styled_heading}\n")
 
     def write_usage(self, prog: str, args: str = "", prefix: str = "Usage: ") -> None: