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

plain/cli/chores.py

@@ -7,79 +7,77 @@ logger = logging.getLogger("plain.chores")
 
 
 @click.group()
-def chores():
+def chores() -> None:
     """Routine maintenance tasks"""
     pass
 
 
 @chores.command("list")
-@click.option("--group", default=None, type=str, help="Group to run", multiple=True)
 @click.option(
     "--name", default=None, type=str, help="Name of the chore to run", multiple=True
 )
-def list_chores(group, name):
-    """
-    List all registered chores.
-    """
+def list_chores(name: tuple[str, ...]) -> None:
+    """List all registered chores"""
     from plain.chores.registry import chores_registry
 
     chores_registry.import_modules()
 
-    if group or name:
-        chores = [
-            chore
-            for chore in chores_registry.get_chores()
-            if (chore.group in group or not group) and (chore.name in name or not name)
+    chore_classes = chores_registry.get_chores()
+
+    if name:
+        chore_classes = [
+            chore_class
+            for chore_class in chore_classes
+            if f"{chore_class.__module__}.{chore_class.__qualname__}" in name
         ]
-    else:
-        chores = chores_registry.get_chores()
 
-    for chore in chores:
-        click.secho(f"{chore}", bold=True, nl=False)
-        if chore.description:
-            click.echo(f": {chore.description}")
+    for chore_class in chore_classes:
+        chore_name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        click.secho(f"{chore_name}", bold=True, nl=False)
+        description = chore_class.__doc__.strip() if chore_class.__doc__ else ""
+        if description:
+            click.secho(f": {description}", dim=True)
         else:
             click.echo("")
 
 
 @chores.command("run")
-@click.option("--group", default=None, type=str, help="Group to run", multiple=True)
 @click.option(
     "--name", default=None, type=str, help="Name of the chore to run", multiple=True
 )
 @click.option(
     "--dry-run", is_flag=True, help="Show what would be done without executing"
 )
-def run_chores(group, name, dry_run):
-    """
-    Run the specified chores.
-    """
+def run_chores(name: tuple[str, ...], dry_run: bool) -> None:
+    """Run specified chores"""
     from plain.chores.registry import chores_registry
 
     chores_registry.import_modules()
 
-    if group or name:
-        chores = [
-            chore
-            for chore in chores_registry.get_chores()
-            if (chore.group in group or not group) and (chore.name in name or not name)
+    chore_classes = chores_registry.get_chores()
+
+    if name:
+        chore_classes = [
+            chore_class
+            for chore_class in chore_classes
+            if f"{chore_class.__module__}.{chore_class.__qualname__}" in name
         ]
-    else:
-        chores = chores_registry.get_chores()
 
     chores_failed = []
 
-    for chore in chores:
-        click.echo(f"{chore.name}:", nl=False)
+    for chore_class in chore_classes:
+        chore_name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        click.echo(f"{chore_name}:", nl=False)
         if dry_run:
-            click.echo(" (dry run)", fg="yellow")
+            click.secho(" (dry run)", fg="yellow", nl=False)
         else:
             try:
+                chore = chore_class()
                 result = chore.run()
             except Exception:
                 click.secho(" Failed", fg="red")
-                chores_failed.append(chore)
-                logger.exception(f"Error running chore {chore.name}")
+                chores_failed.append(chore_class)
+                logger.exception(f"Error running chore {chore_name}")
                 continue
 
             if result is None:

plain/cli/core.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import traceback
+from typing import Any
 
 import click
 from click.core import Command, Context
@@ -15,8 +18,10 @@ from .formatting import PlainContext
 from .install import install
 from .preflight import preflight_cli
 from .registry import cli_registry
+from .request import request
 from .scaffold import create
-from .settings import setting
+from .server import server
+from .settings import settings
 from .shell import run, shell
 from .upgrade import upgrade
 from .urls import urls
@@ -24,12 +29,13 @@ from .utils import utils
 
 
 @click.group()
-def plain_cli():
+def plain_cli() -> None:
     pass
 
 
-plain_cli.add_command(agent)
 plain_cli.add_command(docs)
+plain_cli.add_command(request)
+plain_cli.add_command(agent)
 plain_cli.add_command(preflight_cli)
 plain_cli.add_command(create)
 plain_cli.add_command(chores)
@@ -37,11 +43,12 @@ plain_cli.add_command(build)
 plain_cli.add_command(utils)
 plain_cli.add_command(urls)
 plain_cli.add_command(changelog)
-plain_cli.add_command(setting)
+plain_cli.add_command(settings)
 plain_cli.add_command(shell)
 plain_cli.add_command(run)
 plain_cli.add_command(install)
 plain_cli.add_command(upgrade)
+plain_cli.add_command(server)
 
 
 class CLIRegistryGroup(click.Group):
@@ -49,42 +56,49 @@ class CLIRegistryGroup(click.Group):
     Click Group that exposes commands from the CLI registry.
     """
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
         cli_registry.import_modules()
 
-    def list_commands(self, ctx):
+    def list_commands(self, ctx: Context) -> list[str]:
         return sorted(cli_registry.get_commands().keys())
 
-    def get_command(self, ctx, name):
+    def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
         commands = cli_registry.get_commands()
-        return commands.get(name)
+        return commands.get(cmd_name)
 
 
 class PlainCommandCollection(click.CommandCollection):
     context_class = PlainContext
 
-    def __init__(self, *args, **kwargs):
-        sources = []
+    def __init__(self, *args: Any, **kwargs: Any):
+        # Start with only built-in commands (no setup needed)
+        sources = [plain_cli]
+
+        super().__init__(*args, **kwargs)
+        self.sources = sources
+        self._registry_group = None
+        self._setup_attempted = False
+
+    def _ensure_registry_loaded(self) -> None:
+        """Lazy load the registry group (requires setup)."""
+        if self._registry_group is not None or self._setup_attempted:
+            return
+
+        self._setup_attempted = True
 
         try:
             plain.runtime.setup()
-
-            sources = [
-                CLIRegistryGroup(),
-                plain_cli,
-            ]
+            self._registry_group = CLIRegistryGroup()
+            # Add registry group to sources
+            self.sources.insert(0, self._registry_group)
         except plain.runtime.AppPathNotFound:
-            # Allow some commands to work regardless of being in a valid app
+            # Allow built-in commands to work regardless of being in a valid app
             click.secho(
                 "Plain `app` directory not found. Some commands may be missing.",
                 fg="yellow",
                 err=True,
             )
-
-            sources = [
-                plain_cli,
-            ]
         except ImproperlyConfigured as e:
             # Show what was configured incorrectly and exit
             click.secho(
@@ -92,7 +106,6 @@ class PlainCommandCollection(click.CommandCollection):
                 fg="red",
                 err=True,
             )
-
             exit(1)
         except Exception as e:
             # Show the exception and exit
@@ -105,19 +118,90 @@ class PlainCommandCollection(click.CommandCollection):
                 fg="red",
                 err=True,
             )
-
             exit(1)
 
-        super().__init__(*args, **kwargs)
-
-        self.sources = sources
-
     def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        # Try built-in commands first
         cmd = super().get_command(ctx, cmd_name)
+
+        if cmd is None:
+            # Command not found in built-ins, try registry (requires setup)
+            self._ensure_registry_loaded()
+            cmd = super().get_command(ctx, cmd_name)
+        elif not getattr(cmd, "without_runtime_setup", False):
+            # Command found but needs setup - ensure registry is loaded
+            self._ensure_registry_loaded()
+
         if cmd:
             # Pass the formatting down to subcommands automatically
             cmd.context_class = self.context_class
         return cmd
 
+    def list_commands(self, ctx: Context) -> list[str]:
+        # For help listing, we need to show registry commands too
+        self._ensure_registry_loaded()
+        return super().list_commands(ctx)
+
+    def format_commands(self, ctx: Context, formatter: Any) -> None:
+        """Format commands with separate sections for common, core, and package commands."""
+        self._ensure_registry_loaded()
+
+        # Get all commands from both sources, tracking their source
+        commands = []
+        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:
+                    # source_index 0 = plain_cli (core), 1+ = registry (packages)
+                    commands.append((name, cmd, source_index))
+
+        if not commands:
+            return
+
+        # Get metadata from the registry (for shortcuts)
+        shortcuts_metadata = cli_registry.get_shortcuts()
+
+        # 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:
+                # 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/cli/docs.py

@@ -1,18 +1,51 @@
 import importlib.util
+import pkgutil
 from pathlib import Path
 
 import click
 
+from .llmdocs import LLMDocs
 from .output import iterate_markdown
 
 
 @click.command()
-@click.option("--open")
+@click.option("--open", is_flag=True, help="Open the README in your default editor")
+@click.option("--source", is_flag=True, help="Include symbolicated source code")
+@click.option("--list", "show_list", is_flag=True, help="List available packages")
 @click.argument("module", default="")
-def docs(module, open):
+def docs(module: str, open: bool, source: bool, show_list: bool) -> None:
+    """Show documentation for a package"""
+    if show_list:
+        # List available packages
+        available_packages = []
+        try:
+            import plain
+
+            # Check core plain package (namespace package)
+            plain_spec = importlib.util.find_spec("plain")
+            if plain_spec and plain_spec.submodule_search_locations:
+                available_packages.append("plain")
+
+            # Check other plain.* subpackages
+            if hasattr(plain, "__path__"):
+                for importer, modname, ispkg in pkgutil.iter_modules(
+                    plain.__path__, "plain."
+                ):
+                    if ispkg:
+                        available_packages.append(modname)
+        except Exception:
+            pass
+
+        if available_packages:
+            for pkg in sorted(available_packages):
+                click.echo(f"- {pkg}")
+        else:
+            click.echo("No packages found.")
+        return
+
     if not module:
         raise click.UsageError(
-            "You must specify a module. For LLM-friendly docs, use `plain agent docs`."
+            "You must specify a module. Use --list to see available packages."
         )
 
     # Convert hyphens to dots (e.g., plain-models -> plain.models)
@@ -22,17 +55,25 @@ def docs(module, open):
     if not module.startswith("plain"):
         module = f"plain.{module}"
 
-    # Get the README.md file for the module
+    # Get the module path
     spec = importlib.util.find_spec(module)
-    if not spec:
+    if not spec or not spec.origin:
         raise click.UsageError(f"Module {module} not found")
 
     module_path = Path(spec.origin).parent
-    readme_path = module_path / "README.md"
-    if not readme_path.exists():
-        raise click.UsageError(f"README.md not found for {module}")
 
-    if open:
-        click.launch(str(readme_path))
+    if source:
+        # Output with symbolicated source
+        source_docs = LLMDocs([module_path])
+        source_docs.load()
+        source_docs.print(relative_to=module_path.parent)
     else:
-        click.echo_via_pager(iterate_markdown(readme_path.read_text()))
+        # Human-readable README output
+        readme_path = module_path / "README.md"
+        if not readme_path.exists():
+            raise click.UsageError(f"README.md not found for {module}")
+
+        if open:
+            click.launch(str(readme_path))
+        else:
+            click.echo_via_pager(iterate_markdown(readme_path.read_text()))

plain/cli/formatting.py

@@ -1,24 +1,29 @@
+from __future__ import annotations
+
 import os
+from typing import Any
 
 import click
 from click.formatting import iter_rows, measure_table, term_len, wrap_text
 
 
 class PlainHelpFormatter(click.HelpFormatter):
-    def write_heading(self, heading):
-        styled_heading = click.style(heading, underline=True)
+    def write_heading(self, heading: str) -> None:
+        styled_heading = click.style(heading, dim=True)
         self.write(f"{'':>{self.current_indent}}{styled_heading}\n")
 
-    def write_usage(self, prog, args, prefix="Usage: "):
-        prefix_styled = click.style(prefix, italic=True)
+    def write_usage(  # type: ignore[override]
+        self, prog: str, args: str = "", prefix: str = "Usage: "
+    ) -> None:
+        prefix_styled = click.style(prefix, dim=True)
         super().write_usage(prog, args, prefix=prefix_styled)
 
-    def write_dl(
+    def write_dl(  # type: ignore[override]
         self,
-        rows,
-        col_max=30,
-        col_spacing=2,
-    ):
+        rows: list[tuple[str, str]],
+        col_max: int = 20,
+        col_spacing: int = 2,
+    ) -> None:
         """Writes a definition list into the buffer.  This is how options
         and commands are usually formatted.
 
@@ -51,10 +56,15 @@ class PlainHelpFormatter(click.HelpFormatter):
             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")
 
@@ -62,12 +72,25 @@ class PlainHelpFormatter(click.HelpFormatter):
 class PlainContext(click.Context):
     formatter_class = PlainHelpFormatter
 
-    def __init__(self, *args, **kwargs):
+    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
-        if any(
-            os.getenv(var)
-            for var in ["CI", "FORCE_COLOR", "GITHUB_ACTIONS", "GITLAB_CI"]
-        ) and not any(os.getenv(var) for var in ["NO_COLOR", "PYTEST_CURRENT_TEST"]):
+        # Follow CLICOLOR standard (http://bixense.com/clicolors/)
+        # Priority: NO_COLOR > CLICOLOR_FORCE/FORCE_COLOR > CI detection > CLICOLOR > isatty
+        if os.getenv("NO_COLOR") or os.getenv("PYTEST_CURRENT_TEST"):
+            self.color = False
+        elif os.getenv("CLICOLOR_FORCE") or os.getenv("FORCE_COLOR"):
+            self.color = True
+        elif os.getenv("CI"):
+            # Enable colors in CI/deployment environments even without TTY
+            # This matches behavior of modern tools like uv (via Rust's anstyle)
             self.color = True
+        elif os.getenv("CLICOLOR"):
+            # CLICOLOR=1 means use colors only if TTY (Click's default behavior)
+            pass  # Let Click handle it with isatty check
+        # Otherwise use Click's default behavior (isatty check)

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")