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

plain/cli/build.py

@@ -9,6 +9,7 @@ import click
 
 import plain.runtime
 from plain.assets.compile import compile_assets, get_compiled_path
+from plain.cli.print import print_event
 
 
 @click.command()
@@ -33,8 +34,8 @@ from plain.assets.compile import compile_assets, get_compiled_path
     default=True,
     help="Compress the assets",
 )
-def build(keep_original, fingerprint, compress):
-    """Pre-deployment build step (compile assets, css, js, etc.)"""
+def build(keep_original: bool, fingerprint: bool, compress: bool) -> None:
+    """Pre-deployment build step for assets and static files"""
 
     if not keep_original and not fingerprint:
         raise click.UsageError(
@@ -54,18 +55,16 @@ def build(keep_original, fingerprint, compress):
             .get("run", {})
             .items()
         ):
-            click.secho(f"Running {name} from pyproject.toml", bold=True)
+            print_event(f"{name}...")
             result = subprocess.run(data["cmd"], shell=True)
-            print()
             if result.returncode:
                 click.secho(f"Error in {name} (exit {result.returncode})", fg="red")
                 sys.exit(result.returncode)
 
     # Then run installed package build steps (like tailwind, typically should run last...)
     for entry_point in entry_points(group="plain.build"):
-        click.secho(f"Running {entry_point.name}", bold=True)
-        result = entry_point.load()()
-        print()
+        print_event(f"{entry_point.name}...")
+        entry_point.load()()
 
     # Compile our assets
     target_dir = get_compiled_path()
@@ -79,7 +78,7 @@ def build(keep_original, fingerprint, compress):
     total_compiled = 0
 
     for url_path, resolved_url_path, compiled_paths in compile_assets(
-        target_dir=target_dir,
+        target_dir=str(target_dir),
         keep_original=keep_original,
         fingerprint=fingerprint,
         compress=compress,

plain/cli/changelog.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import re
 from importlib.util import find_spec
 from pathlib import Path
@@ -5,9 +7,10 @@ from pathlib import Path
 import click
 
 from .output import style_markdown
+from .runtime import without_runtime_setup
 
 
-def parse_version(version_str):
+def parse_version(version_str: str) -> tuple[int, ...]:
     """Parse a version string into a tuple of integers for comparison."""
     # Remove 'v' prefix if present and split by dots
     clean_version = version_str.lstrip("v")
@@ -22,7 +25,7 @@ def parse_version(version_str):
     return tuple(parts)
 
 
-def compare_versions(v1, v2):
+def compare_versions(v1: str, v2: str) -> int:
     """Compare two version strings. Returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2."""
     parsed_v1 = parse_version(v1)
     parsed_v2 = parse_version(v2)
@@ -40,12 +43,15 @@ def compare_versions(v1, v2):
         return 0
 
 
+@without_runtime_setup
 @click.command("changelog")
 @click.argument("package_label")
 @click.option("--from", "from_version", help="Show entries from this version onwards")
 @click.option("--to", "to_version", help="Show entries up to this version")
-def changelog(package_label, from_version, to_version):
-    """Show changelog entries for a package."""
+def changelog(
+    package_label: str, from_version: str | None, to_version: str | None
+) -> None:
+    """Show changelog for a package"""
     module_name = package_label.replace("-", ".")
     spec = find_spec(module_name)
     if not spec:
@@ -85,7 +91,7 @@ def changelog(package_label, from_version, to_version):
     if current_version is not None:
         entries.append((current_version, current_lines))
 
-    def version_found(version):
+    def version_found(version: str) -> bool:
         return any(compare_versions(v, version) == 0 for v, _ in entries)
 
     if from_version and not version_found(from_version):

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,38 +1,115 @@
+from __future__ import annotations
+
 import importlib.util
 from pathlib import Path
 
 import click
 
-from .output import iterate_markdown
+from .llmdocs import LLMDocs
+
+# All known official Plain packages: pip name -> short description
+KNOWN_PACKAGES = {
+    "plain": "Web framework core",
+    "plain-admin": "Backend admin interface",
+    "plain-api": "Class-based API views",
+    "plain-auth": "User authentication and authorization",
+    "plain-cache": "Database-backed cache with optional expiration",
+    "plain-code": "Preconfigured code formatting and linting",
+    "plain-dev": "Local development server with auto-reload",
+    "plain-elements": "HTML template components",
+    "plain-email": "Send email",
+    "plain-esbuild": "Build JavaScript with esbuild",
+    "plain-flags": "Feature flags via database models",
+    "plain-htmx": "HTMX integration for templates and views",
+    "plain-jobs": "Background jobs with a database-driven queue",
+    "plain-loginlink": "Link-based authentication",
+    "plain-models": "Model data and store it in a database",
+    "plain-oauth": "OAuth provider login",
+    "plain-observer": "On-page telemetry and observability",
+    "plain-pages": "Serve static pages, markdown, and assets",
+    "plain-pageviews": "Client-side pageview tracking",
+    "plain-passwords": "Password authentication",
+    "plain-pytest": "Test with pytest",
+    "plain-redirection": "URL redirection with admin and logging",
+    "plain-scan": "Test for production best practices",
+    "plain-sessions": "Database-backed sessions",
+    "plain-start": "Bootstrap a new project from templates",
+    "plain-support": "Support forms for your application",
+    "plain-tailwind": "Tailwind CSS without JavaScript or npm",
+    "plain-toolbar": "Debug toolbar",
+    "plain-tunnel": "Remote access to local dev server",
+    "plain-vendor": "Vendor CDN scripts and styles",
+}
+
+
+def _normalize_module(module: str) -> str:
+    """Normalize a module string to dotted form (e.g. plain-models -> plain.models)."""
+    module = module.replace("-", ".")
+    if not module.startswith("plain"):
+        module = f"plain.{module}"
+    return module
+
+
+def _pip_package_name(module: str) -> str:
+    """Convert a dotted module name to a pip package name (e.g. plain.models -> plain-models)."""
+    return module.replace(".", "-")
+
+
+def _is_installed(module: str) -> bool:
+    """Check if a dotted module name is installed."""
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ModuleNotFoundError, ValueError):
+        return False
+
+
+def _online_docs_url(pip_name: str) -> str:
+    """Return the online documentation URL for a package."""
+    module = pip_name.replace("-", ".")
+    return f"https://plainframework.com/docs/{pip_name}/{module.replace('.', '/')}/"
 
 
 @click.command()
-@click.option("--open")
+@click.option("--symbols", is_flag=True, help="Show symbolicated API surface only")
+@click.option("--list", "show_list", is_flag=True, help="List available packages")
 @click.argument("module", default="")
-def docs(module, open):
+def docs(module: str, symbols: bool, show_list: bool) -> None:
+    """Show documentation for a package"""
+    if show_list:
+        for pip_name in sorted(KNOWN_PACKAGES):
+            description = KNOWN_PACKAGES[pip_name]
+            dotted = pip_name.replace("-", ".")
+            installed = _is_installed(dotted)
+            status = " (installed)" if installed else ""
+            click.echo(f"  {pip_name}{status} — {description}")
+        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)
-    module = module.replace("-", ".")
+    module = _normalize_module(module)
 
-    # Automatically prefix if we need to
-    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:
-        raise click.UsageError(f"Module {module} not found")
+    if not spec or not spec.origin:
+        pip_name = _pip_package_name(module)
+        if pip_name in KNOWN_PACKAGES:
+            msg = (
+                f"{module} is not installed.\n\n"
+                f"  Online docs:  {_online_docs_url(pip_name)}"
+            )
+        else:
+            msg = f"Module {module} not found. Use --list to see available packages."
+        raise click.UsageError(msg)
 
     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))
-    else:
-        click.echo_via_pager(iterate_markdown(readme_path.read_text()))
+
+    llm_docs = LLMDocs([module_path])
+    llm_docs.load()
+    llm_docs.print(
+        relative_to=module_path.parent,
+        include_docs=not symbols,
+        include_symbols=symbols,
+    )

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)