plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/cli/install.py

@@ -3,28 +3,11 @@ import sys
 
 import click
 
-from .agent.prompt import prompt_agent
-
 
 @click.command()
 @click.argument("packages", nargs=-1, required=True)
-@click.option(
-    "--agent-command",
-    envvar="PLAIN_AGENT_COMMAND",
-    help="Run command with generated prompt",
-)
-@click.option(
-    "--print",
-    "print_only",
-    is_flag=True,
-    help="Print the prompt without running the agent",
-)
-def install(
-    packages: tuple[str, ...],
-    agent_command: str | None = None,
-    print_only: bool = False,
-) -> None:
-    """Install Plain packages with the help of an agent."""
+def install(packages: tuple[str, ...]) -> None:
+    """Install Plain packages"""
     # Validate all package names
     invalid_packages = [pkg for pkg in packages if not pkg.startswith("plain")]
     if invalid_packages:
@@ -33,14 +16,14 @@ def install(
             "This command is only for Plain framework packages."
         )
 
-    # Install all packages first
+    # Install all packages
     if len(packages) == 1:
-        click.secho(f"Installing {packages[0]}...", bold=True, err=True)
+        click.secho(f"Installing {packages[0]}...", bold=True)
     else:
-        click.secho(f"Installing {len(packages)} packages...", bold=True, err=True)
+        click.secho(f"Installing {len(packages)} packages...", bold=True)
         for pkg in packages:
-            click.secho(f"  - {pkg}", err=True)
-        click.echo(err=True)
+            click.secho(f"  - {pkg}")
+        click.echo()
 
     install_cmd = ["uv", "add"] + list(packages)
     result = subprocess.run(install_cmd, check=False, stderr=sys.stderr)
@@ -48,35 +31,8 @@ def install(
     if result.returncode != 0:
         raise click.ClickException("Failed to install packages")
 
-    click.echo(err=True)
+    click.echo()
     if len(packages) == 1:
-        click.secho(f"✓ {packages[0]} installed successfully", fg="green", err=True)
+        click.secho(f"{packages[0]} installed successfully", fg="green")
     else:
-        click.secho(
-            f"✓ {len(packages)} packages installed successfully", fg="green", err=True
-        )
-    click.echo(err=True)
-
-    # Build the prompt for the agent to complete setup
-    lines = [
-        f"Complete the setup for the following Plain packages that were just installed: {', '.join(packages)}",
-        "",
-        "## Instructions",
-        "",
-        "For each package:",
-        "1. Run `uv run plain docs <package>` and read the installation instructions",
-        "2. If the docs point out that it is a --dev tool, move it to the dev dependencies in pyproject.toml: `uv remove <package> && uv add <package> --dev`",
-        "3. Go through the installation instructions and complete any code modifications that are needed",
-        "",
-        "DO NOT commit any changes",
-        "",
-        "Report back with:",
-        "- Whether the setup completed successfully",
-        "- Any manual steps that the user will need to complete",
-        "- Any issues or errors encountered",
-    ]
-
-    prompt = "\n".join(lines)
-    success = prompt_agent(prompt, agent_command, print_only)
-    if not success:
-        raise click.Abort()
+        click.secho(f"{len(packages)} packages installed successfully", fg="green")

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 agents 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 "/agents/" 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 "/agents/" 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,30 +62,37 @@ class LLMDocs:
         plain_root = Path(*path.parts[: root_index + 1])
         return path.relative_to(plain_root.parent)
 
-    def print(self, relative_to=None):
-        for doc in self.docs:
-            if relative_to:
-                display_path = doc.relative_to(relative_to)
-            else:
-                display_path = self.display_path(doc)
-            click.secho(f"<Docs: {display_path}>", fg="yellow")
-            click.echo(doc.read_text())
-            click.secho(f"</Docs: {display_path}>", fg="yellow")
-            click.echo()
-
-        for source in self.sources:
-            if symbolicated := self.symbolicate(source):
+    def print(
+        self,
+        relative_to: Path | None = None,
+        include_docs: bool = True,
+        include_symbols: bool = True,
+    ) -> None:
+        if include_docs:
+            for doc in self.docs:
                 if relative_to:
-                    display_path = source.relative_to(relative_to)
+                    display_path = doc.relative_to(relative_to)
                 else:
-                    display_path = self.display_path(source)
-                click.secho(f"<Source: {display_path}>", fg="yellow")
-                click.echo(symbolicated)
-                click.secho(f"</Source: {display_path}>", fg="yellow")
+                    display_path = self.display_path(doc)
+                click.secho(f"<Docs: {display_path}>", fg="yellow")
+                click.echo(doc.read_text())
+                click.secho(f"</Docs: {display_path}>", fg="yellow")
                 click.echo()
 
+        if include_symbols:
+            for source in self.sources:
+                if symbolicated := self.symbolicate(source):
+                    if relative_to:
+                        display_path = source.relative_to(relative_to)
+                    else:
+                        display_path = self.display_path(source)
+                    click.secho(f"<Source: {display_path}>", fg="yellow")
+                    click.echo(symbolicated)
+                    click.secho(f"</Source: {display_path}>", fg="yellow")
+                    click.echo()
+
     @staticmethod
-    def symbolicate(file_path: Path):
+    def symbolicate(file_path: Path) -> str:
         if "internal" in str(file_path).split("/"):
             return ""
 
@@ -89,8 +100,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 +123,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