plain 0.68.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,25 +1,20 @@
 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
-from plain.preflight.registry import checks_registry
-from plain.runtime import settings
 
 
-@click.group("preflight")
-def preflight_cli():
-    """Run or manage preflight checks."""
-    pass
-
-
-@preflight_cli.command("check")
+@common_command
+@click.command("preflight")
 @click.option(
     "--deploy",
     is_flag=True,
-    help="Check deployment settings.",
+    help="Include deployment checks.",
 )
 @click.option(
     "--format",
@@ -32,16 +27,18 @@ def preflight_cli():
     is_flag=True,
     help="Hide progress output and warnings, only show errors.",
 )
-def check_command(deploy, format, quiet):
-    """
-    Use the system check framework to validate entire Plain project.
-    Exit with error code if any errors are found. Warnings do not cause failure.
-    """
+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"
+
     # 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=True)
+        click.secho(
+            "Running preflight checks...", dim=True, italic=True, err=use_stderr
+        )
 
     total_checks = 0
     passed_checks = 0
@@ -60,23 +57,23 @@ def check_command(deploy, format, quiet):
         if format == "text":
             if not quiet:
                 # Print check name without newline
-                click.echo("Check:", nl=False, err=True)
-                click.secho(f"{check_name} ", bold=True, nl=False, err=True)
+                click.echo("Check:", nl=False, err=use_stderr)
+                click.secho(f"{check_name} ", bold=True, nl=False, err=use_stderr)
 
             # Determine status icon based on issue severity
             if not visible_issues:
                 # No issues - passed
                 if not quiet:
-                    click.secho("✔", fg="green", err=True)
+                    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=True)
+                        click.secho("✗", fg="red", err=use_stderr)
                     else:
-                        click.secho("⚠", fg="yellow", err=True)
+                        click.secho("⚠", fg="yellow", err=use_stderr)
 
                 # Print issues with simple indentation
                 issues_to_show = (
@@ -91,26 +88,26 @@ def check_command(deploy, format, quiet):
                     if quiet:
                         # In quiet mode, show check name once, then issues
                         if i == 0:
-                            click.secho(f"{check_name}:", err=True)
+                            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=True,
+                            err=use_stderr,
                             nl=False,
                         )
-                        click.secho(f" {issue.fix}", err=True, dim=True)
+                        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=True,
+                            err=use_stderr,
                             nl=False,
                         )
-                        click.secho(f"{issue.fix}", err=True, dim=True)
+                        click.secho(f"{issue.fix}", err=use_stderr, dim=True)
         else:
             # For JSON format, just count passed checks
             if not visible_issues:
@@ -129,12 +126,12 @@ def check_command(deploy, format, quiet):
 
     if format == "json":
         # Build JSON output
-        results = {"passed": not has_errors, "checks": []}
+        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 = {
+            check_result: dict[str, Any] = {
                 "name": check_name,
                 "passed": len(visible_issues) == 0,
                 "issues": [],
@@ -195,53 +192,8 @@ def check_command(deploy, format, quiet):
 
         summary_text = ", ".join(summary_parts) if summary_parts else "no issues"
 
-        click.secho(f"{icon}{summary_text}", fg=summary_color, err=True)
+        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)
-
-
-@preflight_cli.command("list")
-def list_checks():
-    """List all available preflight checks."""
-    packages_registry.autodiscover_modules("preflight", include_app=True)
-
-    regular = []
-    deployment = []
-    silenced_checks = settings.PREFLIGHT_SILENCED_CHECKS
-
-    for name, (check_class, deploy) in sorted(checks_registry.checks.items()):
-        # Use class docstring as description
-        description = check_class.__doc__ or "No description"
-        # Get first line of docstring
-        description = description.strip().split("\n")[0]
-
-        is_silenced = name in silenced_checks
-        if deploy:
-            deployment.append((name, description, is_silenced))
-        else:
-            regular.append((name, description, is_silenced))
-
-    if regular:
-        click.echo("Regular checks:")
-        for name, description, is_silenced in regular:
-            silenced_text = (
-                click.style(" (silenced)", fg="red", dim=True) if is_silenced else ""
-            )
-            click.echo(
-                f"  {click.style(name)}: {click.style(description, dim=True)}{silenced_text}"
-            )
-
-    if deployment:
-        click.echo("\nDeployment checks:")
-        for name, description, is_silenced in deployment:
-            silenced_text = (
-                click.style(" (silenced)", fg="red", dim=True) if is_silenced else ""
-            )
-            click.echo(
-                f"  {click.style(name)}: {click.style(description, dim=True)}{silenced_text}"
-            )
-
-    if not regular and not deployment:
-        click.echo("No preflight checks found.")

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,45 +1,131 @@
+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.
         """
         packages_registry.autodiscover_modules("cli", include_app=True)
 
-    def get_commands(self):
+    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_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

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

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import json
+from typing import Any
 
 import click
 
@@ -37,8 +40,28 @@ from plain.test import Client
     multiple=True,
     help="Additional headers (format: 'Name: Value')",
 )
-def request(path, method, data, user_id, follow, content_type, headers):
-    """Make an HTTP request using the test client against the development database."""
+@click.option(
+    "--no-headers",
+    is_flag=True,
+    help="Hide response headers from output",
+)
+@click.option(
+    "--no-body",
+    is_flag=True,
+    help="Hide response body from output",
+)
+def request(
+    path: str,
+    method: str,
+    data: str | None,
+    user_id: str | None,
+    follow: bool,
+    content_type: str | None,
+    headers: tuple[str, ...],
+    no_headers: bool,
+    no_body: bool,
+) -> None:
+    """Make HTTP requests against the dev database"""
 
     try:
         # Only allow in DEBUG mode for security
@@ -61,9 +84,6 @@ def request(path, method, data, user_id, follow, content_type, headers):
                 try:
                     user = User.query.get(id=user_id)
                     client.force_login(user)
-                    click.secho(
-                        f"Authenticated as user {user_id}", fg="green", dim=True
-                    )
                 except User.DoesNotExist:
                     click.secho(f"User {user_id} not found", fg="red", err=True)
                     return
@@ -90,11 +110,11 @@ def request(path, method, data, user_id, follow, content_type, headers):
 
         # Make the request
         method = method.upper()
-        kwargs = {
-            "path": path,
+        kwargs: dict[str, Any] = {
             "follow": follow,
-            "headers": header_dict or None,
         }
+        if header_dict:
+            kwargs["headers"] = header_dict
 
         if method in ("POST", "PUT", "PATCH") and data:
             kwargs["data"] = data
@@ -103,57 +123,71 @@ def request(path, method, data, user_id, follow, content_type, headers):
 
         # Call the appropriate client method
         if method == "GET":
-            response = client.get(**kwargs)
+            response = client.get(path, **kwargs)
         elif method == "POST":
-            response = client.post(**kwargs)
+            response = client.post(path, **kwargs)
         elif method == "PUT":
-            response = client.put(**kwargs)
+            response = client.put(path, **kwargs)
         elif method == "PATCH":
-            response = client.patch(**kwargs)
+            response = client.patch(path, **kwargs)
         elif method == "DELETE":
-            response = client.delete(**kwargs)
+            response = client.delete(path, **kwargs)
         elif method == "HEAD":
-            response = client.head(**kwargs)
+            response = client.head(path, **kwargs)
         elif method == "OPTIONS":
-            response = client.options(**kwargs)
+            response = client.options(path, **kwargs)
         elif method == "TRACE":
-            response = client.trace(**kwargs)
+            response = client.trace(path, **kwargs)
         else:
             click.secho(f"Unsupported HTTP method: {method}", fg="red", err=True)
             return
 
         # Display response information
-        click.secho(
-            f"HTTP {response.status_code}",
-            fg="green" if response.status_code < 400 else "red",
-            bold=True,
-        )
+        click.secho("Response:", fg="yellow", bold=True)
 
-        # Show additional response info first
-        if hasattr(response, "user"):
-            click.secho(f"Authenticated user: {response.user}", fg="blue", dim=True)
+        # Status code
+        click.echo(f"  Status: {response.status_code}")
 
-        if hasattr(response, "resolver_match") and response.resolver_match:
+        # Request ID
+        click.echo(f"  Request ID: {response.wsgi_request.unique_id}")
+
+        # User
+        if response.user:
+            click.echo(f"  Authenticated user: {response.user}")
+
+        # URL pattern
+        if response.resolver_match:
             match = response.resolver_match
-            url_name = match.namespaced_url_name or match.url_name or "unnamed"
-            click.secho(f"URL pattern matched: {url_name}", fg="blue", dim=True)
+            namespaced_url_name = getattr(match, "namespaced_url_name", None)
+            url_name_attr = getattr(match, "url_name", None)
+            url_name = namespaced_url_name or url_name_attr
+            if url_name:
+                click.echo(f"  URL pattern: {url_name}")
+
+        click.echo()
 
         # Show headers
-        if response.headers:
+        if response.headers and not no_headers:
             click.secho("Response Headers:", fg="yellow", bold=True)
             for key, value in response.headers.items():
                 click.echo(f"  {key}: {value}")
             click.echo()
 
         # Show response content last
-        if response.content:
+        if response.content and not no_body:
             content_type = response.headers.get("Content-Type", "")
 
             if "json" in content_type.lower():
                 try:
-                    json_data = response.json()
-                    click.secho("Response Body (JSON):", fg="yellow", bold=True)
-                    click.echo(json.dumps(json_data, indent=2))
+                    # The test client adds a json() method to the response
+                    json_method = getattr(response, "json", None)
+                    if json_method and callable(json_method):
+                        json_data: Any = json_method()
+                        click.secho("Response Body (JSON):", fg="yellow", bold=True)
+                        click.echo(json.dumps(json_data, indent=2))
+                    else:
+                        click.secho("Response Body:", fg="yellow", bold=True)
+                        click.echo(response.content.decode("utf-8", errors="replace"))
                 except Exception:
                     click.secho("Response Body:", fg="yellow", bold=True)
                     click.echo(response.content.decode("utf-8", errors="replace"))
@@ -165,7 +199,7 @@ def request(path, method, data, user_id, follow, content_type, headers):
                 click.secho("Response Body:", fg="yellow", bold=True)
                 content = response.content.decode("utf-8", errors="replace")
                 click.echo(content)
-        else:
+        elif not no_body:
             click.secho("(No response body)", fg="yellow", dim=True)
 
     except Exception as e:

plain/cli/runtime.py

@@ -0,0 +1,45 @@
+"""
+CLI runtime utilities.
+
+This module provides decorators and utilities for CLI commands.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable)
+
+
+def without_runtime_setup(f: F) -> F:
+    """
+    Decorator to mark commands that don't need plain.runtime.setup().
+
+    Use this for commands that don't access settings or app code,
+    particularly for commands that fork (like server) where setup()
+    should happen in the worker process, not the parent.
+
+    Example:
+        @without_runtime_setup
+        @click.command()
+        def server(**options):
+            ...
+    """
+    f.without_runtime_setup = True  # dynamic attribute for decorator
+    return f
+
+
+def common_command(f: F) -> F:
+    """
+    Decorator to mark commands as commonly used.
+
+    Common commands are shown in a separate "Common Commands" section
+    in the help output, making them easier to discover.
+
+    Example:
+        @common_command
+        @click.command()
+        def dev(**options):
+            ...
+    """
+    f.is_common_command = True  # dynamic attribute for decorator
+    return f