plain 0.60.0__py3-none-any.whl → 0.61.0__py3-none-any.whl

plain/AGENTS.md

@@ -0,0 +1,14 @@
+# Plain AGENTS.md
+
+Plain is a Python web framework that was originally forked from Django. While it still has a lot in common with Django, there are also significant changes -- don't solely rely on knowledge of Django when working with Plain.
+
+## Commands
+
+The `plain` CLI is the main entrypoint for the framework. If `plain` is not available by itself, try `uv run plain`.
+
+- `plain shell -c <command>`: Run a Python command with Plain configured.
+- `plain run <filename>`: Run a Python script with Plain configured.
+- `plain agent docs <package>`: Show README.md and symbolicated source files for a specific package.
+- `plain agent docs --list`: List packages with docs available.
+- `plain agent request <path> --user <user_id>`: Make an authenticated request to the application and inspect the output.
+- `plain --help`: List all available commands (including those from installed packages)

plain/CHANGELOG.md

@@ -1,5 +1,19 @@
 # plain changelog
 
+## [0.61.0](https://github.com/dropseed/plain/releases/plain@0.61.0) (2025-09-03)
+
+### What's changed
+
+- Added new `plain agent` command with subcommands for coding agents including `docs`, `md`, and `request` ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+- Added `-c` option to `plain shell` to execute commands and exit, similar to `python -c` ([5e67f0b](https://github.com/dropseed/plain/commit/5e67f0bcd8))
+- The `plain docs --llm` functionality has been moved to `plain agent docs` command ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+- Removed the `plain help` command in favor of standard `plain --help` ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+
+### Upgrade instructions
+
+- Replace `plain docs --llm` usage with `plain agent docs` command
+- Use `plain --help` instead of `plain help` command
+
 ## [0.60.0](https://github.com/dropseed/plain/releases/plain@0.60.0) (2025-08-27)
 
 ### What's changed

plain/cli/agent/__init__.py

@@ -0,0 +1,20 @@
+import click
+
+from .docs import docs
+from .md import md
+from .request import request
+
+
+@click.group("agent", invoke_without_command=True)
+@click.pass_context
+def agent(ctx):
+    """Tools for coding agents."""
+    if ctx.invoked_subcommand is None:
+        # If no subcommand provided, show all AGENTS.md files
+        ctx.invoke(md, show_all=True, show_list=False, package="")
+
+
+# Add commands to the group
+agent.add_command(docs)
+agent.add_command(md)
+agent.add_command(request)

plain/cli/agent/docs.py

@@ -0,0 +1,80 @@
+import importlib.util
+import pkgutil
+from pathlib import Path
+
+import click
+
+from .llmdocs import LLMDocs
+
+
+@click.command()
+@click.argument("package", default="", required=False)
+@click.option(
+    "--list",
+    "show_list",
+    is_flag=True,
+    help="List available packages",
+)
+def docs(package, show_list):
+    """Show LLM-friendly documentation and source for a package."""
+
+    if show_list:
+        # List available packages using same discovery logic as md command
+        try:
+            available_packages = []
+
+            # Check for plain.* subpackages (including core plain)
+            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
+                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.")
+        except Exception as e:
+            click.echo(f"Error listing packages: {e}")
+        return
+
+    if not package:
+        raise click.UsageError(
+            "Package name required. Usage: plain agent docs [package-name]"
+        )
+
+    # Convert hyphens to dots (e.g., plain-models -> plain.models)
+    package = package.replace("-", ".")
+
+    # Automatically prefix if we need to
+    if not package.startswith("plain"):
+        package = f"plain.{package}"
+
+    try:
+        # Get the path for this specific package
+        spec = importlib.util.find_spec(package)
+        if not spec or not spec.origin:
+            raise click.UsageError(f"Package {package} not found")
+
+        package_path = Path(spec.origin).parent
+        paths = [package_path]
+
+        # Generate docs for this specific package
+        source_docs = LLMDocs(paths)
+        source_docs.load()
+        source_docs.print(relative_to=package_path.parent)
+
+    except Exception as e:
+        raise click.UsageError(f"Error loading documentation for {package}: {e}")

plain/cli/agent/llmdocs.py

@@ -0,0 +1,145 @@
+import ast
+from pathlib import Path
+
+import click
+
+
+class LLMDocs:
+    """Generates LLM-friendly documentation."""
+
+    def __init__(self, paths):
+        self.paths = paths
+
+    def load(self):
+        self.docs = set()
+        self.sources = set()
+
+        for path in self.paths:
+            if path.is_dir():
+                self.docs.update(path.glob("**/*.md"))
+                self.sources.update(path.glob("**/*.py"))
+            elif path.suffix == ".py":
+                self.sources.add(path)
+            elif path.suffix == ".md":
+                self.docs.add(path)
+
+        # Exclude "migrations" code from plain apps, except for plain/models/migrations
+        # Also exclude CHANGELOG.md and AGENTS.md
+        self.docs = {
+            doc
+            for doc in self.docs
+            if not (
+                "/migrations/" in str(doc)
+                and "/plain/models/migrations/" not in str(doc)
+            )
+            and doc.name not in ("CHANGELOG.md", "AGENTS.md")
+        }
+        self.sources = {
+            source
+            for source in self.sources
+            if not (
+                "/migrations/" in str(source)
+                and "/plain/models/migrations/" not in str(source)
+            )
+            and source.name != "cli.py"
+        }
+
+        self.docs = sorted(self.docs)
+        self.sources = sorted(self.sources)
+
+    def display_path(self, path):
+        if "plain" in path.parts:
+            root_index = path.parts.index("plain")
+        elif "plainx" in path.parts:
+            root_index = path.parts.index("plainx")
+        else:
+            raise ValueError("Path does not contain 'plain' or 'plainx'")
+
+        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):
+                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):
+        if "internal" in str(file_path).split("/"):
+            return ""
+
+        source = file_path.read_text()
+
+        parsed = ast.parse(source)
+
+        def should_skip(node):
+            if isinstance(node, ast.ClassDef | ast.FunctionDef):
+                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.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.startswith("_"):
+                        return True
+            return False
+
+        def process_node(node, indent=0):
+            lines = []
+            prefix = "    " * indent
+
+            if should_skip(node):
+                return []
+
+            if isinstance(node, ast.ClassDef):
+                decorators = [
+                    f"{prefix}@{ast.unparse(d)}"
+                    for d in node.decorator_list
+                    if not (isinstance(d, ast.Name) and d.id == "internalcode")
+                ]
+                lines.extend(decorators)
+                bases = [ast.unparse(base) for base in node.bases]
+                lines.append(f"{prefix}class {node.name}({', '.join(bases)})")
+                for child in node.body:
+                    child_lines = process_node(child, indent + 1)
+                    if child_lines:
+                        lines.extend(child_lines)
+
+            elif isinstance(node, ast.FunctionDef):
+                decorators = [f"{prefix}@{ast.unparse(d)}" for d in node.decorator_list]
+                lines.extend(decorators)
+                args = ast.unparse(node.args)
+                lines.append(f"{prefix}def {node.name}({args})")
+
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        lines.append(f"{prefix}{target.id} = {ast.unparse(node.value)}")
+
+            return lines
+
+        symbolicated_lines = []
+        for node in parsed.body:
+            symbolicated_lines.extend(process_node(node))
+
+        return "\n".join(symbolicated_lines)

plain/cli/agent/md.py

@@ -0,0 +1,87 @@
+import importlib.util
+import pkgutil
+from pathlib import Path
+
+import click
+
+from ..output import iterate_markdown
+
+
+def _get_packages_with_agents():
+    """Get dict mapping package names to AGENTS.md paths."""
+    agents_files = {}
+
+    # Check for plain.* subpackages (including core plain)
+    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:
+            # For namespace packages, use the first search location
+            plain_path = Path(plain_spec.submodule_search_locations[0])
+            agents_path = plain_path / "AGENTS.md"
+            if agents_path.exists():
+                agents_files["plain"] = agents_path
+
+        # Check other plain.* subpackages
+        for importer, modname, ispkg in pkgutil.iter_modules(plain.__path__, "plain."):
+            if ispkg:
+                try:
+                    spec = importlib.util.find_spec(modname)
+                    if spec and spec.origin:
+                        package_path = Path(spec.origin).parent
+                        # Look for AGENTS.md at package root
+                        agents_path = package_path / "AGENTS.md"
+                        if agents_path.exists():
+                            agents_files[modname] = agents_path
+                except Exception:
+                    continue
+    except Exception:
+        pass
+
+    return agents_files
+
+
+@click.command("md")
+@click.argument("package", default="", required=False)
+@click.option(
+    "--all",
+    "show_all",
+    is_flag=True,
+    help="Show AGENTS.md for all packages that have them",
+)
+@click.option(
+    "--list",
+    "show_list",
+    is_flag=True,
+    help="List packages with AGENTS.md files",
+)
+def md(package, show_all, show_list):
+    """Show AGENTS.md for a package."""
+
+    agents_files = _get_packages_with_agents()
+
+    if show_list:
+        for pkg in sorted(agents_files.keys()):
+            click.echo(f"- {pkg}")
+
+        return
+
+    if show_all:
+        for pkg in sorted(agents_files.keys()):
+            agents_path = agents_files[pkg]
+            for line in iterate_markdown(agents_path.read_text()):
+                click.echo(line, nl=False)
+            print()
+
+        return
+
+    if not package:
+        raise click.UsageError(
+            "Package name or --all required. Use --list to see available packages."
+        )
+
+    agents_path = agents_files[package]
+    for line in iterate_markdown(agents_path.read_text()):
+        click.echo(line, nl=False)

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

@@ -5,24 +5,19 @@ import subprocess
 import click
 
 
+def is_agent_environment():
+    """Check if we're running inside a coding agent."""
+    return bool(
+        os.environ.get("CLAUDECODE")
+        or os.environ.get("CODEX_SANDBOX")
+        or os.environ.get("CURSOR_ENVIRONMENT")
+    )
+
+
 def prompt_agent(
     prompt: str, agent_command: str | None = None, print_only: bool = False
 ) -> bool:
-    """
-    Run an agent command with the given prompt, or display the prompt for manual copying.
-
-    Args:
-        prompt: The prompt to send to the agent
-        agent_command: Optional command to run (e.g., "claude code"). If not provided,
-                      will check the PLAIN_AGENT_COMMAND environment variable.
-        print_only: If True, always print the prompt instead of running the agent
-
-    Returns:
-        True if the agent command succeeded (or no agent command was provided),
-        False if the agent command failed.
-    """
-    # Check if running inside an agent and just print the prompt if so
-    if os.environ.get("CLAUDECODE") or os.environ.get("CODEX_SANDBOX"):
+    if is_agent_environment():
         click.echo(prompt)
         return True
 

plain/cli/agent/request.py

@@ -0,0 +1,181 @@
+import json
+
+import click
+
+from plain.runtime import settings
+from plain.test import Client
+
+
+@click.command()
+@click.argument("path")
+@click.option(
+    "--method",
+    default="GET",
+    help="HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)",
+)
+@click.option(
+    "--data",
+    help="Request data (JSON string for POST/PUT/PATCH)",
+)
+@click.option(
+    "--user",
+    "user_id",
+    help="User ID to authenticate as (skips normal authentication)",
+)
+@click.option(
+    "--follow/--no-follow",
+    default=True,
+    help="Follow redirects (default: True)",
+)
+@click.option(
+    "--content-type",
+    help="Content-Type header for request data",
+)
+@click.option(
+    "--header",
+    "headers",
+    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."""
+
+    try:
+        # Only allow in DEBUG mode for security
+        if not settings.DEBUG:
+            click.secho("This command only works when DEBUG=True", fg="red", err=True)
+            return
+
+        # Temporarily add testserver to ALLOWED_HOSTS so the test client can make requests
+        original_allowed_hosts = settings.ALLOWED_HOSTS
+        settings.ALLOWED_HOSTS = ["*"]
+
+        try:
+            # Create test client
+            client = Client()
+
+            # If user_id provided, force login
+            if user_id:
+                try:
+                    # Get the User model using plain.auth utility
+                    from plain.auth import get_user_model
+
+                    User = get_user_model()
+
+                    # Get the user
+                    try:
+                        user = User.objects.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
+
+                except Exception as e:
+                    click.secho(f"Authentication error: {e}", fg="red", err=True)
+                    return
+
+            # Parse additional headers
+            header_dict = {}
+            for header in headers:
+                if ":" in header:
+                    key, value = header.split(":", 1)
+                    header_dict[key.strip()] = value.strip()
+
+            # Prepare request data
+            if data and content_type and "json" in content_type.lower():
+                try:
+                    # Validate JSON
+                    json.loads(data)
+                except json.JSONDecodeError as e:
+                    click.secho(f"Invalid JSON data: {e}", fg="red", err=True)
+                    return
+
+            # Make the request
+            method = method.upper()
+            kwargs = {
+                "path": path,
+                "follow": follow,
+                "headers": header_dict or None,
+            }
+
+            if method in ("POST", "PUT", "PATCH") and data:
+                kwargs["data"] = data
+                if content_type:
+                    kwargs["content_type"] = content_type
+
+            # Call the appropriate client method
+            if method == "GET":
+                response = client.get(**kwargs)
+            elif method == "POST":
+                response = client.post(**kwargs)
+            elif method == "PUT":
+                response = client.put(**kwargs)
+            elif method == "PATCH":
+                response = client.patch(**kwargs)
+            elif method == "DELETE":
+                response = client.delete(**kwargs)
+            elif method == "HEAD":
+                response = client.head(**kwargs)
+            elif method == "OPTIONS":
+                response = client.options(**kwargs)
+            elif method == "TRACE":
+                response = client.trace(**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,
+            )
+
+            # Show additional response info first
+            if hasattr(response, "user"):
+                click.secho(f"Authenticated user: {response.user}", fg="blue", dim=True)
+
+            if hasattr(response, "resolver_match") and 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)
+
+            # Show headers
+            if response.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:
+                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))
+                    except Exception:
+                        click.secho("Response Body:", fg="yellow", bold=True)
+                        click.echo(response.content.decode("utf-8", errors="replace"))
+                elif "html" in content_type.lower():
+                    click.secho("Response Body (HTML):", fg="yellow", bold=True)
+                    content = response.content.decode("utf-8", errors="replace")
+                    click.echo(content)
+                else:
+                    click.secho("Response Body:", fg="yellow", bold=True)
+                    content = response.content.decode("utf-8", errors="replace")
+                    click.echo(content)
+            else:
+                click.secho("(No response body)", fg="yellow", dim=True)
+
+        finally:
+            # Restore original ALLOWED_HOSTS
+            settings.ALLOWED_HOSTS = original_allowed_hosts
+
+    except Exception as e:
+        click.secho(f"Request failed: {e}", fg="red", err=True)

plain/cli/core.py

@@ -6,12 +6,12 @@ from click.core import Command, Context
 import plain.runtime
 from plain.exceptions import ImproperlyConfigured
 
+from .agent import agent
 from .build import build
 from .changelog import changelog
 from .chores import chores
 from .docs import docs
 from .formatting import PlainContext
-from .help import help_cmd
 from .install import install
 from .preflight import preflight_checks
 from .registry import cli_registry
@@ -28,6 +28,7 @@ def plain_cli():
     pass
 
 
+plain_cli.add_command(agent)
 plain_cli.add_command(docs)
 plain_cli.add_command(preflight_checks)
 plain_cli.add_command(create)
@@ -41,7 +42,6 @@ plain_cli.add_command(shell)
 plain_cli.add_command(run)
 plain_cli.add_command(install)
 plain_cli.add_command(upgrade)
-plain_cli.add_command(help_cmd)
 
 
 class CLIRegistryGroup(click.Group):

plain/cli/docs.py

@@ -1,218 +1,38 @@
-import ast
 import importlib.util
 from pathlib import Path
 
 import click
 
-from plain.packages import packages_registry
-
 from .output import iterate_markdown
 
 
 @click.command()
-@click.option("--llm", "llm", is_flag=True)
 @click.option("--open")
 @click.argument("module", default="")
-def docs(module, llm, open):
-    if not module and not llm:
-        raise click.UsageError("You must specify a module or use --llm")
-
-    if llm:
-        paths = [Path(__file__).parent.parent]
-
-        for package_config in packages_registry.get_package_configs():
-            if package_config.name.startswith("app."):
-                # Ignore app packages for now
-                continue
-
-            paths.append(Path(package_config.path))
-
-        source_docs = LLMDocs(paths)
-        source_docs.load()
-        source_docs.print()
-
-        click.secho(
-            "That's everything! Copy this into your AI tool of choice.",
-            err=True,
-            fg="green",
+def docs(module, open):
+    if not module:
+        raise click.UsageError(
+            "You must specify a module. For LLM-friendly docs, use `plain agent docs`."
         )
 
-        return
-
-    if module:
-        # Convert hyphens to dots (e.g., plain-models -> plain.models)
-        module = module.replace("-", ".")
-
-        # Automatically prefix if we need to
-        if not module.startswith("plain"):
-            module = f"plain.{module}"
-
-        # Get the README.md file for the module
-        spec = importlib.util.find_spec(module)
-        if not spec:
-            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))
-        else:
-            click.echo_via_pager(iterate_markdown(readme_path.read_text()))
-
-
-class LLMDocs:
-    preamble = (
-        "Below is all of the documentation and abbreviated source code for the Plain web framework. "
-        "Your job is to read and understand it, and then act as the Plain Framework Assistant and "
-        "help the developer accomplish whatever they want to do next."
-        "\n\n---\n\n"
-    )
-
-    def __init__(self, paths):
-        self.paths = paths
-
-    def load(self):
-        self.docs = set()
-        self.sources = set()
-
-        for path in self.paths:
-            if path.is_dir():
-                self.docs.update(path.glob("**/*.md"))
-                self.sources.update(path.glob("**/*.py"))
-            elif path.suffix == ".py":
-                self.sources.add(path)
-            elif path.suffix == ".md":
-                self.docs.add(path)
-
-        # Exclude "migrations" code from plain apps, except for plain/models/migrations
-        self.docs = {
-            doc
-            for doc in self.docs
-            if not (
-                "/migrations/" in str(doc)
-                and "/plain/models/migrations/" not in str(doc)
-            )
-        }
-        self.sources = {
-            source
-            for source in self.sources
-            if not (
-                "/migrations/" in str(source)
-                and "/plain/models/migrations/" not in str(source)
-            )
-        }
-
-        self.docs = sorted(self.docs)
-        self.sources = sorted(self.sources)
-
-    def display_path(self, path):
-        if "plain" in path.parts:
-            root_index = path.parts.index("plain")
-        elif "plainx" in path.parts:
-            root_index = path.parts.index("plainx")
-        else:
-            raise ValueError("Path does not contain 'plain' or 'plainx'")
-
-        plain_root = Path(*path.parts[: root_index + 1])
-        return path.relative_to(plain_root.parent)
-
-    def print(self, relative_to=None):
-        click.secho(self.preamble, fg="yellow")
-
-        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):
-                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):
-        if "internal" in str(file_path).split("/"):
-            return ""
-
-        source = file_path.read_text()
-
-        parsed = ast.parse(source)
-
-        def should_skip(node):
-            if isinstance(node, ast.ClassDef | ast.FunctionDef):
-                if any(
-                    isinstance(d, ast.Name) and d.id == "internalcode"
-                    for d in node.decorator_list
-                ):
-                    return True
-                if node.name.startswith("_"):  # and not node.name.endswith("__"):
-                    return True
-            elif isinstance(node, ast.Assign):
-                for target in node.targets:
-                    if (
-                        isinstance(target, ast.Name) and target.id.startswith("_")
-                        # and not target.id.endswith("__")
-                    ):
-                        return True
-            return False
-
-        def process_node(node, indent=0):
-            lines = []
-            prefix = "    " * indent
-
-            if should_skip(node):
-                return []
-
-            if isinstance(node, ast.ClassDef):
-                decorators = [
-                    f"{prefix}@{ast.unparse(d)}"
-                    for d in node.decorator_list
-                    if not (isinstance(d, ast.Name) and d.id == "internalcode")
-                ]
-                lines.extend(decorators)
-                bases = [ast.unparse(base) for base in node.bases]
-                lines.append(f"{prefix}class {node.name}({', '.join(bases)})")
-                # if ast.get_docstring(node):
-                #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
-                for child in node.body:
-                    child_lines = process_node(child, indent + 1)
-                    if child_lines:
-                        lines.extend(child_lines)
-                # if not has_body:
-                #     lines.append(f"{prefix}    pass")
-
-            elif isinstance(node, ast.FunctionDef):
-                decorators = [f"{prefix}@{ast.unparse(d)}" for d in node.decorator_list]
-                lines.extend(decorators)
-                args = ast.unparse(node.args)
-                lines.append(f"{prefix}def {node.name}({args})")
-                # if ast.get_docstring(node):
-                #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
-                # lines.append(f"{prefix}    pass")
+    # Convert hyphens to dots (e.g., plain-models -> plain.models)
+    module = module.replace("-", ".")
 
-            elif isinstance(node, ast.Assign):
-                for target in node.targets:
-                    if isinstance(target, ast.Name):
-                        lines.append(f"{prefix}{target.id} = {ast.unparse(node.value)}")
+    # Automatically prefix if we need to
+    if not module.startswith("plain"):
+        module = f"plain.{module}"
 
-            return lines
+    # Get the README.md file for the module
+    spec = importlib.util.find_spec(module)
+    if not spec:
+        raise click.UsageError(f"Module {module} not found")
 
-        symbolicated_lines = []
-        for node in parsed.body:
-            symbolicated_lines.extend(process_node(node))
+    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}")
 
-        return "\n".join(symbolicated_lines)
+    if open:
+        click.launch(str(readme_path))
+    else:
+        click.echo_via_pager(iterate_markdown(readme_path.read_text()))

plain/cli/install.py

@@ -3,7 +3,7 @@ import sys
 
 import click
 
-from .agent import prompt_agent
+from .agent.prompt import prompt_agent
 
 
 @click.command()

plain/cli/shell.py

@@ -12,12 +12,26 @@ import click
     type=click.Choice(["ipython", "bpython", "python"]),
     help="Specify an interactive interpreter interface.",
 )
-def shell(interface):
+@click.option(
+    "-c",
+    "--command",
+    help="Execute the given command and exit.",
+)
+def shell(interface, command):
     """
     Runs a Python interactive interpreter. Tries to use IPython or
     bpython, if one of them is available.
     """
 
+    if command:
+        # Execute the command and exit
+        before_script = "import plain.runtime; plain.runtime.setup()"
+        full_command = f"{before_script}; {command}"
+        result = subprocess.run(["python", "-c", full_command])
+        if result.returncode:
+            sys.exit(result.returncode)
+        return
+
     if interface:
         interface = [interface]
     else:

plain/cli/upgrade.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import click
 
-from .agent import prompt_agent
+from .agent.prompt import prompt_agent
 
 LOCK_FILE = Path("uv.lock")
 

plain/templates/AGENTS.md

@@ -0,0 +1,3 @@
+# Plain Templates AGENTS.md
+
+- Plain templates use Jinja2.

plain/views/objects.py

@@ -1,4 +1,5 @@
 from functools import cached_property
+from typing import Any
 
 from plain.exceptions import ImproperlyConfigured, ObjectDoesNotExist
 from plain.forms import Form
@@ -38,19 +39,19 @@ class ObjectTemplateViewMixin:
     context_object_name = ""
 
     @cached_property
-    def object(self):
+    def object(self) -> Any:
         try:
             obj = self.get_object()
         except ObjectDoesNotExist:
             raise Http404
 
+        # Also raise 404 if get_object() returns None
         if not obj:
-            # Also raise 404 if the object is None
             raise Http404
 
         return obj
 
-    def get_object(self):  # Intentionally untyped... subclasses must override this.
+    def get_object(self) -> Any:
         raise NotImplementedError(
             f"get_object() is not implemented on {self.__class__.__name__}"
         )

{plain-0.60.0.dist-info → plain-0.61.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.60.0
+Version: 0.61.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.60.0.dist-info → plain-0.61.0.dist-info}/RECORD

@@ -1,4 +1,5 @@
-plain/CHANGELOG.md,sha256=D_pNXRYALt2M76lgFw0DsNBweBA3wjnESTQycSEMz68,10968
+plain/AGENTS.md,sha256=Euyn6UG9gumJj1vXi6PFPmhRAlwedUfK7UcYTBF9Y9Y,893
+plain/CHANGELOG.md,sha256=X0ep2U-LXpociHtkEk-PTB30VVFiZHOocGunQgrqGAQ,11831
 plain/README.md,sha256=5BJyKhf0TDanWVbOQyZ3zsi5Lov9xk-LlJYCDWofM6Y,4078
 plain/__main__.py,sha256=GK39854Lc_LO_JP8DzY9Y2MIQ4cQEl7SXFJy244-lC8,110
 plain/debug.py,sha256=XdjnXcbPGsi0J2SpHGaLthhYU5AjhBlkHdemaP4sbYY,758
@@ -20,26 +21,30 @@ plain/chores/__init__.py,sha256=r9TXtQCH-VbvfnIJ5F8FxgQC35GRWFOfmMZN3q9niLg,67
 plain/chores/registry.py,sha256=V3WjuekRI22LFvJbqSkUXQtiOtuE2ZK8gKV1TRvxRUI,1866
 plain/cli/README.md,sha256=5C7vsH0ISxu7q5H6buC25MBOILkI_rzdySitswpQgJw,1032
 plain/cli/__init__.py,sha256=6w9T7K2WrPwh6DcaMb2oNt_CWU6Bc57nUTO2Bt1p38Y,63
-plain/cli/agent.py,sha256=nf-Tuc3abxpyV-nShBn1wq0JWjfgd3zY9lLH6rAZSRs,1678
 plain/cli/build.py,sha256=Lo6AYghJz0DM9fIVUSiBSOKa5vR0XCOxZWEjza6sc8Q,3172
 plain/cli/changelog.py,sha256=j-k1yZk9mpm-fLZgeWastiyIisxNSuAJfXTQ2B6WQmk,3457
 plain/cli/chores.py,sha256=xXSSFvr8T5jWfLWqe6E8YVMw1BkQxyOHHVuY0x9RH0A,2412
-plain/cli/core.py,sha256=HZZcDVNEMAhantDM4Hnug-SrwU3YgAq1-KDa3_a9-K0,3111
-plain/cli/docs.py,sha256=MjFIpNc0FsHACi_spPVumXM-oPCi__3U0Jqf41lqjQM,7481
+plain/cli/core.py,sha256=g0D1OZkYGWt05-V1oDNzX2wcoCIAxrZjlgaQs2qWLlc,3106
+plain/cli/docs.py,sha256=YEEE-Th1CSxiL-wj5fF-ZagqkqAZYkEPRMO1OYUsQrU,1066
 plain/cli/formatting.py,sha256=1hZH13y1qwHcU2K2_Na388nw9uvoeQH8LrWL-O9h8Yc,2207
-plain/cli/help.py,sha256=NefZSEIixrX_WELVSnJDHRpLDWf7_4PXmkkMm3Q2mzo,787
-plain/cli/install.py,sha256=wvEc3gLP5tvSb1Xwm2467DCXqCPTWxuzktGnlK94SGg,2784
+plain/cli/install.py,sha256=mffSYBmSJSj44OPBfu53nBQoyoz4jk69DvppubIB0mU,2791
 plain/cli/output.py,sha256=Fe3xS6Va4Bi1ZNrqi0nh09THTsdCyMW2b9SPY5I4n-o,1318
 plain/cli/preflight.py,sha256=8tHBD4L4nPLUKThfaYx3SUZSJzC48oV2m_Hbn6W4ODc,4124
 plain/cli/print.py,sha256=XraUYrgODOJquIiEv78wSCYGRBplHXtXSS9QtFG5hqY,217
 plain/cli/registry.py,sha256=yKVMSDjW8g10nlV9sPXFGJQmhC_U-k4J4kM7N2OQVLA,1467
 plain/cli/scaffold.py,sha256=mcywA9DzfwoBSqWl5-Zpgcy1mTNUGEgdvoxXUrGcEVk,1351
 plain/cli/settings.py,sha256=9cx4bue664I2P7kUedlf4YhCPB0tSKSE4Q8mGyzEv2o,1995
-plain/cli/shell.py,sha256=iIwvlTdTBjLBBUdXMAmIRWSoynszOZI79-mrBg4RegU,1373
+plain/cli/shell.py,sha256=PMHdwcRv48qXDToeq82aZaNth-cKc3V2pQ1yISrNMvY,1802
 plain/cli/startup.py,sha256=wLaFuyUb4ewWhtehBCGicrRCXIIGCRbeCT3ce9hUv-A,1022
-plain/cli/upgrade.py,sha256=eGVWm0gpn-Pr6uPsfzojRmh_VU5--B0h9dYfQuXSzi8,5625
+plain/cli/upgrade.py,sha256=T8u81rA2_dSfJaK4vF1_OPkQpspBVWnlPxatyk_mdx0,5632
 plain/cli/urls.py,sha256=ghCW36aRszxmTo06A50FIvYopb6kQ07QekkDzM6_A1o,3824
 plain/cli/utils.py,sha256=VwlIh0z7XxzVV8I3qM2kZo07fkJFPoeeVZa1ODG616k,258
+plain/cli/agent/__init__.py,sha256=Ipp65kuIF14TVxNqsj71MsWUePaKHUcdP3QmaYyNcg0,480
+plain/cli/agent/docs.py,sha256=ubX3ZeRHxVaetLk9fjiN9mJ07GZExC-CHUvQoX2DD7c,2464
+plain/cli/agent/llmdocs.py,sha256=AUpNDb1xSOsSpzGOiFvpzUe4f7PUGMiR9cI13aVZouo,5038
+plain/cli/agent/md.py,sha256=7r1II8ckubBFOZNGPASWaPmJdgByWFPINLqIOzRetLQ,2581
+plain/cli/agent/prompt.py,sha256=rugYyQHV7JDNqGrx3_PPShwwqYlnEVbxw8RsczOo8tg,1253
+plain/cli/agent/request.py,sha256=JILrcxEMPagBXWrjNGMy3qatCYCXw-_uJMKkVHk_bho,6549
 plain/csrf/README.md,sha256=ApWpB-qlEf0LkOKm9Yr-6f_lB9XJEvGFDo_fraw8ghI,2391
 plain/csrf/middleware.py,sha256=d_vb8l0-KxzyqCivVq0jTCsFOm-ljwjmjVuZXKVYR5U,5113
 plain/csrf/views.py,sha256=HwQqfI6KPelHP9gSXhjfZaTLQic71PKsoZ6DPhr1rKI,572
@@ -98,6 +103,7 @@ plain/signals/__init__.py,sha256=eAs0kLqptuP6I31dWXeAqRNji3svplpAV4Ez6ktjwXM,131
 plain/signals/dispatch/__init__.py,sha256=FzEygqV9HsM6gopio7O2Oh_X230nA4d5Q9s0sUjMq0E,292
 plain/signals/dispatch/dispatcher.py,sha256=VxSlqn9PCOTghPPJLOqZPs6FNQZfV2BJpMfFMSg6Dtc,11531
 plain/signals/dispatch/license.txt,sha256=o9EhDhsC4Q5HbmD-IfNGVTEkXtNE33r5rIt3lleJ8gc,1727
+plain/templates/AGENTS.md,sha256=o6H_qEZ2eY5IrNmSZG7o7ZYfqdD0SkJm_2VPBaaOo5w,59
 plain/templates/README.md,sha256=QAQxoygpc0CE13fh4eH4ZILwl2xc-oMdGKtiZLLrNCk,2565
 plain/templates/__init__.py,sha256=bX76FakE9T7mfK3N0deN85HlwHNQpeigytSC9Z8LcOs,451
 plain/templates/core.py,sha256=mbcH0yTeFOI3XOg9dYSroXRIcdv9sETEy4HzY-ugwco,1258
@@ -149,11 +155,11 @@ plain/views/base.py,sha256=CC9UvMZeAjVvi90vGjoZzsQ0jnhbg3-7qCKQ8-Pb6cg,4184
 plain/views/errors.py,sha256=jbNCJIzowwCsEvqyJ3opMeZpPDqTyhtrbqb0VnAm2HE,1263
 plain/views/exceptions.py,sha256=b4euI49ZUKS9O8AGAcFfiDpstzkRAuuj_uYQXzWNHME,138
 plain/views/forms.py,sha256=ESZOXuo6IeYixp1RZvPb94KplkowRiwO2eGJCM6zJI0,2400
-plain/views/objects.py,sha256=YNb8MO1I99HTmQghC5nFk25TQmaB_s45K5yg5BGt4qY,5018
+plain/views/objects.py,sha256=v3Vgvdoc1s0QW6JNWWrO5XXy9zF7vgwndgxX1eOSQoE,4999
 plain/views/redirect.py,sha256=Xpb3cB7nZYvKgkNqcAxf9Jwm2SWcQ0u2xz4oO5M3vP8,1909
 plain/views/templates.py,sha256=oAlebEyfES0rzBhfyEJzFmgLkpkbleA6Eip-8zDp-yk,1863
-plain-0.60.0.dist-info/METADATA,sha256=w-VNXX3R5YsTPJ_UBnFSzu33jUHnwPHAQdzMJZxILhc,4488
-plain-0.60.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain-0.60.0.dist-info/entry_points.txt,sha256=nn4uKTRRZuEKOJv3810s3jtSMW0Gew7XDYiKIvBRR6M,93
-plain-0.60.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.60.0.dist-info/RECORD,,
+plain-0.61.0.dist-info/METADATA,sha256=9fm4uV_Uo8yyhaMeWayg-UyS4_y1_W6sI_tKNONklAY,4488
+plain-0.61.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain-0.61.0.dist-info/entry_points.txt,sha256=nn4uKTRRZuEKOJv3810s3jtSMW0Gew7XDYiKIvBRR6M,93
+plain-0.61.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.61.0.dist-info/RECORD,,

plain/cli/help.py

@@ -1,27 +0,0 @@
-import click
-from click.core import Group
-
-
-@click.command("help")
-@click.pass_context
-def help_cmd(ctx):
-    """Show help for all commands and subcommands."""
-
-    root = ctx.parent.command
-    info_name = ctx.parent.info_name or "plain"
-
-    def print_help(cmd, prog, parent=None):
-        sub_ctx = click.Context(cmd, info_name=prog, parent=parent)
-
-        title = sub_ctx.command_path
-        click.secho(title, fg="green", bold=True)
-        click.secho("-" * len(title), fg="green")
-        click.echo(sub_ctx.get_help())
-
-        if isinstance(cmd, Group):
-            for name in cmd.list_commands(sub_ctx):
-                click.echo()
-                sub_cmd = cmd.get_command(sub_ctx, name)
-                print_help(sub_cmd, name, sub_ctx)
-
-    print_help(root, info_name)