plain 0.66.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/cli/{agent/llmdocs.py → llmdocs.py}

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import ast
 from pathlib import Path
 
@@ -7,10 +9,10 @@ import click
 class LLMDocs:
     """Generates LLM-friendly documentation."""
 
-    def __init__(self, paths):
+    def __init__(self, paths: list[Path]):
         self.paths = paths
 
-    def load(self):
+    def load(self) -> None:
         self.docs = set()
         self.sources = set()
 
@@ -24,7 +26,7 @@ class LLMDocs:
                 self.docs.add(path)
 
         # Exclude "migrations" code from plain apps, except for plain/models/migrations
-        # Also exclude CHANGELOG.md and AGENTS.md
+        # Also exclude CHANGELOG.md, AGENTS.md, and skills directory
         self.docs = {
             doc
             for doc in self.docs
@@ -33,6 +35,7 @@ class LLMDocs:
                 and "/plain/models/migrations/" not in str(doc)
             )
             and doc.name not in ("CHANGELOG.md", "AGENTS.md")
+            and "/skills/" not in str(doc)
         }
         self.sources = {
             source
@@ -42,12 +45,13 @@ class LLMDocs:
                 and "/plain/models/migrations/" not in str(source)
             )
             and source.name != "cli.py"
+            and "/skills/" not in str(source)
         }
 
         self.docs = sorted(self.docs)
         self.sources = sorted(self.sources)
 
-    def display_path(self, path):
+    def display_path(self, path: Path) -> Path:
         if "plain" in path.parts:
             root_index = path.parts.index("plain")
         elif "plainx" in path.parts:
@@ -58,7 +62,7 @@ class LLMDocs:
         plain_root = Path(*path.parts[: root_index + 1])
         return path.relative_to(plain_root.parent)
 
-    def print(self, relative_to=None):
+    def print(self, relative_to: Path | None = None) -> None:
         for doc in self.docs:
             if relative_to:
                 display_path = doc.relative_to(relative_to)
@@ -81,7 +85,7 @@ class LLMDocs:
                 click.echo()
 
     @staticmethod
-    def symbolicate(file_path: Path):
+    def symbolicate(file_path: Path) -> str:
         if "internal" in str(file_path).split("/"):
             return ""
 
@@ -89,8 +93,16 @@ class LLMDocs:
 
         parsed = ast.parse(source)
 
-        def should_skip(node):
-            if isinstance(node, ast.ClassDef | ast.FunctionDef):
+        def should_skip(node: ast.AST) -> bool:
+            if isinstance(node, ast.ClassDef):
+                if any(
+                    isinstance(d, ast.Name) and d.id == "internalcode"
+                    for d in node.decorator_list
+                ):
+                    return True
+                if node.name.startswith("_"):
+                    return True
+            elif isinstance(node, ast.FunctionDef):
                 if any(
                     isinstance(d, ast.Name) and d.id == "internalcode"
                     for d in node.decorator_list
@@ -104,7 +116,7 @@ class LLMDocs:
                         return True
             return False
 
-        def process_node(node, indent=0):
+        def process_node(node: ast.AST, indent: int = 0) -> list[str]:
             lines = []
             prefix = "    " * indent
 

plain/cli/output.py

@@ -1,11 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
 import click
 
 
-def style_markdown(content):
+def style_markdown(content: str) -> str:
     return "".join(iterate_markdown(content))
 
 
-def iterate_markdown(content):
+def iterate_markdown(content: str) -> Iterator[str]:
     """
     Iterator that does basic markdown for a Click pager.
 

plain/cli/preflight.py

@@ -1,126 +1,199 @@
+import json
+import sys
+from typing import Any
+
 import click
 
 from plain import preflight
+from plain.cli.runtime import common_command
 from plain.packages import packages_registry
 
 
+@common_command
 @click.command("preflight")
-@click.argument("package_label", nargs=-1)
 @click.option(
     "--deploy",
     is_flag=True,
-    help="Check deployment settings.",
+    help="Include deployment checks.",
 )
 @click.option(
-    "--fail-level",
-    default="ERROR",
-    type=click.Choice(["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"]),
-    help="Message level that will cause the command to exit with a non-zero status. Default is ERROR.",
+    "--format",
+    default="text",
+    type=click.Choice(["text", "json"]),
+    help="Output format (default: text)",
 )
 @click.option(
-    "--database",
+    "--quiet",
     is_flag=True,
-    help="Run database related checks as part of preflight.",
+    help="Hide progress output and warnings, only show errors.",
 )
-def preflight_checks(package_label, deploy, fail_level, database):
-    """
-    Use the system check framework to validate entire Plain project.
-    Raise CommandError for any serious message (error or critical errors).
-    If there are only light messages (like warnings), print them to stderr
-    and don't raise an exception.
-    """
-    include_deployment_checks = deploy
-
-    if package_label:
-        package_configs = [
-            packages_registry.get_package_config(label) for label in package_label
-        ]
-    else:
-        package_configs = None
+def preflight_cli(deploy: bool, format: str, quiet: bool) -> None:
+    """Validation checks before deployment"""
+    # Use stderr for progress messages only in JSON mode (keeps stdout clean for parsing)
+    # In text mode, send all output to stdout (so success doesn't appear in error logs)
+    use_stderr = format == "json"
 
-    all_issues = preflight.run_checks(
-        package_configs=package_configs,
-        include_deployment_checks=include_deployment_checks,
-        database=database,
-    )
+    # Auto-discover and load preflight checks
+    packages_registry.autodiscover_modules("preflight", include_app=True)
+    if not quiet:
+        click.secho(
+            "Running preflight checks...", dim=True, italic=True, err=use_stderr
+        )
+
+    total_checks = 0
+    passed_checks = 0
+    check_results = []
+
+    # Run checks and collect results
+    for check_class, check_name, issues in preflight.run_checks(
+        include_deploy_checks=deploy,
+    ):
+        total_checks += 1
+
+        # Filter out silenced issues
+        visible_issues = [issue for issue in issues if not issue.is_silenced()]
+
+        # For text format, show real-time progress
+        if format == "text":
+            if not quiet:
+                # Print check name without newline
+                click.echo("Check:", nl=False, err=use_stderr)
+                click.secho(f"{check_name} ", bold=True, nl=False, err=use_stderr)
 
-    header, body, footer = "", "", ""
-    visible_issue_count = 0  # excludes silenced warnings
-
-    if all_issues:
-        debugs = [
-            e for e in all_issues if e.level < preflight.INFO and not e.is_silenced()
-        ]
-        infos = [
-            e
-            for e in all_issues
-            if preflight.INFO <= e.level < preflight.WARNING and not e.is_silenced()
-        ]
-        warnings = [
-            e
-            for e in all_issues
-            if preflight.WARNING <= e.level < preflight.ERROR and not e.is_silenced()
-        ]
-        errors = [
-            e
-            for e in all_issues
-            if preflight.ERROR <= e.level < preflight.CRITICAL and not e.is_silenced()
-        ]
-        criticals = [
-            e
-            for e in all_issues
-            if preflight.CRITICAL <= e.level and not e.is_silenced()
-        ]
-        sorted_issues = [
-            (criticals, "CRITICALS"),
-            (errors, "ERRORS"),
-            (warnings, "WARNINGS"),
-            (infos, "INFOS"),
-            (debugs, "DEBUGS"),
-        ]
-
-        for issues, group_name in sorted_issues:
-            if issues:
-                visible_issue_count += len(issues)
-                formatted = (
-                    click.style(str(e), fg="red")
-                    if e.is_serious()
-                    else click.style(str(e), fg="yellow")
-                    for e in issues
+            # Determine status icon based on issue severity
+            if not visible_issues:
+                # No issues - passed
+                if not quiet:
+                    click.secho("✔", fg="green", err=use_stderr)
+                passed_checks += 1
+            else:
+                # Has issues - determine icon based on highest severity
+                has_errors = any(not issue.warning for issue in visible_issues)
+                if not quiet:
+                    if has_errors:
+                        click.secho("✗", fg="red", err=use_stderr)
+                    else:
+                        click.secho("⚠", fg="yellow", err=use_stderr)
+
+                # Print issues with simple indentation
+                issues_to_show = (
+                    visible_issues
+                    if not quiet
+                    else [issue for issue in visible_issues if not issue.warning]
                 )
-                formatted = "\n".join(sorted(formatted))
-                body += f"\n{group_name}:\n{formatted}\n"
+                for i, issue in enumerate(issues_to_show):
+                    issue_color = "red" if not issue.warning else "yellow"
+                    issue_type = "ERROR" if not issue.warning else "WARNING"
 
-    if visible_issue_count:
-        header = "Preflight check identified some issues:\n"
+                    if quiet:
+                        # In quiet mode, show check name once, then issues
+                        if i == 0:
+                            click.secho(f"{check_name}:", err=use_stderr)
+                        # Show ID and fix on separate lines with same indentation
+                        click.secho(
+                            f"  [{issue_type}] {issue.id}:",
+                            fg=issue_color,
+                            bold=True,
+                            err=use_stderr,
+                            nl=False,
+                        )
+                        click.secho(f" {issue.fix}", err=use_stderr, dim=True)
+                    else:
+                        # Show ID and fix on separate lines with same indentation
+                        click.secho(
+                            f"    [{issue_type}] {issue.id}: ",
+                            fg=issue_color,
+                            bold=True,
+                            err=use_stderr,
+                            nl=False,
+                        )
+                        click.secho(f"{issue.fix}", err=use_stderr, dim=True)
+        else:
+            # For JSON format, just count passed checks
+            if not visible_issues:
+                passed_checks += 1
 
-    if any(
-        e.is_serious(getattr(preflight, fail_level)) and not e.is_silenced()
-        for e in all_issues
-    ):
-        footer += "\n"
-        footer += "Preflight check identified {} ({} silenced).".format(
-            "no issues"
-            if visible_issue_count == 0
-            else "1 issue"
-            if visible_issue_count == 1
-            else f"{visible_issue_count} issues",
-            len(all_issues) - visible_issue_count,
-        )
-        msg = click.style(f"SystemCheckError: {header}", fg="red") + body + footer
-        raise click.ClickException(msg)
+        check_results.append((check_class, check_name, issues))
+
+    # Output results based on format
+
+    # Get all issues from check_results instead of maintaining separate list
+    all_issues = [issue for _, _, issues in check_results for issue in issues]
+    # Errors (non-warnings) cause preflight to fail
+    has_errors = any(
+        not issue.warning and not issue.is_silenced() for issue in all_issues
+    )
+
+    if format == "json":
+        # Build JSON output
+        results: dict[str, Any] = {"passed": not has_errors, "checks": []}
+
+        for check_class, check_name, issues in check_results:
+            visible_issues = [issue for issue in issues if not issue.is_silenced()]
+
+            check_result: dict[str, Any] = {
+                "name": check_name,
+                "passed": len(visible_issues) == 0,
+                "issues": [],
+            }
+
+            for issue in visible_issues:
+                issue_data = {
+                    "id": issue.id,
+                    "warning": issue.warning,
+                    "fix": issue.fix,
+                    "obj": str(issue.obj) if issue.obj is not None else None,
+                }
+                check_result["issues"].append(issue_data)
+
+            results["checks"].append(check_result)
+
+        click.echo(json.dumps(results, indent=2))
     else:
-        if visible_issue_count:
-            footer += "\n"
-            footer += "Preflight check identified {} ({} silenced).".format(
-                "no issues"
-                if visible_issue_count == 0
-                else "1 issue"
-                if visible_issue_count == 1
-                else f"{visible_issue_count} issues",
-                len(all_issues) - visible_issue_count,
+        # Text format summary
+        if not quiet:
+            click.echo()
+
+        # Calculate warning and error counts
+        warning_count = sum(
+            1
+            for _, _, issues in check_results
+            if issues
+            and not any(
+                not issue.warning for issue in issues if not issue.is_silenced()
             )
-            msg = header + body + footer
-            click.echo(msg, err=True)
+        )
+        error_count = sum(
+            1
+            for _, _, issues in check_results
+            if issues
+            and any(not issue.warning for issue in issues if not issue.is_silenced())
+        )
+
+        # Build colored summary parts
+        summary_parts = []
+
+        if passed_checks > 0:
+            summary_parts.append(click.style(f"{passed_checks} passed", fg="green"))
+
+        if warning_count > 0:
+            summary_parts.append(click.style(f"{warning_count} warnings", fg="yellow"))
+
+        if error_count > 0:
+            summary_parts.append(click.style(f"{error_count} errors", fg="red"))
+
+        # Show checkmark if successful (no errors)
+        if not has_errors:
+            icon = click.style("✔ ", fg="green")
+            summary_color = "green"
         else:
-            click.secho("✔ Checks passed", err=True, fg="green")
+            icon = ""
+            summary_color = None
+
+        summary_text = ", ".join(summary_parts) if summary_parts else "no issues"
+
+        click.secho(f"{icon}{summary_text}", fg=summary_color, err=use_stderr)
+
+    # Exit with error if there are any errors (not warnings)
+    if has_errors:
+        sys.exit(1)

plain/cli/print.py

@@ -1,9 +1,9 @@
 import click
 
 
-def print_event(msg, newline=True):
-    arrow = click.style("-->", fg=214, bold=True)
-    message = str(msg)
+def print_event(msg: str, newline: bool = True) -> None:
+    arrow = click.style("-->", fg=214, bold=True, dim=True)
+    message = click.style(msg, dim=True)
     if not newline:
         message += " "
-    click.secho(f"{arrow} {message}", nl=newline)
+    click.echo(f"{arrow} {message}", nl=newline)

plain/cli/registry.py

@@ -1,62 +1,131 @@
-from importlib import import_module
-from importlib.util import find_spec
+from __future__ import annotations
+
+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
+    is_common: bool = False
+
+
 class CLIRegistry:
-    def __init__(self):
-        self._commands = {}
+    def __init__(self) -> None:
+        self._commands: dict[str, CommandMetadata] = {}
 
-    def register_command(self, cmd, name):
+    def register_command(
+        self,
+        cmd: Any,
+        name: str,
+        shortcut_for: str | None = None,
+        is_common: bool = False,
+    ) -> 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)
+            is_common: Whether this is a commonly used command to show in the "Common Commands" section
         """
-        self._commands[name] = cmd
+        self._commands[name] = CommandMetadata(
+            cmd=cmd, shortcut_for=shortcut_for, is_common=is_common
+        )
 
-    def import_modules(self):
+    def import_modules(self) -> None:
         """
         Import modules from installed packages and app to trigger registration.
         """
-        # Import from installed packages
-        for package_config in packages_registry.get_package_configs():
-            import_name = f"{package_config.name}.cli"
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
+        packages_registry.autodiscover_modules("cli", include_app=True)
 
-        # Import from app
-        import_name = "app.cli"
-        if find_spec(import_name):
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
+    def get_commands(self) -> dict[str, Any]:
+        """
+        Get all registered commands (just the command objects, not metadata).
+        """
+        return {name: metadata.cmd for name, metadata in self._commands.items()}
 
-    def get_commands(self):
+    def get_commands_with_metadata(self) -> dict[str, CommandMetadata]:
         """
-        Get all registered commands.
+        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_common_commands(self) -> dict[str, CommandMetadata]:
+        """
+        Get only commands that are marked as common.
+        """
+        return {
+            name: metadata
+            for name, metadata in self._commands.items()
+            if metadata.is_common
+        }
+
+    def get_regular_commands(self) -> dict[str, CommandMetadata]:
+        """
+        Get only commands that are not common.
+        """
+        return {
+            name: metadata
+            for name, metadata in self._commands.items()
+            if not metadata.is_common
+        }
+
 
 cli_registry = CLIRegistry()
 
 
-def register_cli(name):
+def register_cli(
+    name: str, shortcut_for: str | None = None, common: bool = False
+) -> 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"
+        common: Whether this is a commonly used command to show in the "Common Commands" section
+
     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", common=True)
+        @click.command()
+        def migrate():
+            pass
+
+        # Register a common command
+        @register_cli("dev", common=True)
+        @click.command()
+        def dev():
+            pass
     """
 
-    def wrapper(cmd):
-        cli_registry.register_command(cmd, name)
+    def wrapper(cmd: Any) -> Any:
+        cli_registry.register_command(
+            cmd, name, shortcut_for=shortcut_for, is_common=common
+        )
         return cmd
 
     return wrapper