plain 0.66.0__tar.gz → 0.68.0__tar.gz

{plain-0.66.0 → plain-0.68.0}/PKG-INFO

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

{plain-0.66.0 → plain-0.68.0}/plain/CHANGELOG.md

@@ -1,5 +1,34 @@
 # plain changelog
 
+## [0.68.0](https://github.com/dropseed/plain/releases/plain@0.68.0) (2025-09-25)
+
+### What's changed
+
+- Major refactor of the preflight check system with new CLI commands and improved output ([b0b610d461](https://github.com/dropseed/plain/commit/b0b610d461))
+- Preflight checks now use descriptive IDs instead of numeric codes ([cd96c97b25](https://github.com/dropseed/plain/commit/cd96c97b25))
+- Unified preflight error messages and hints into a single `fix` field ([c7cde12149](https://github.com/dropseed/plain/commit/c7cde12149))
+- Added `plain-upgrade` as a standalone command for upgrading Plain packages ([42f2eed80c](https://github.com/dropseed/plain/commit/42f2eed80c))
+
+### Upgrade instructions
+
+- Use `plain preflight check` instead of `plain preflight` to run all checks
+- Custom preflight checks should be class based, extending `PreflightCheck` and implementing the `run()` method
+- Preflight checks need to be registered with a custom name (ex. `@register_check("app.my_custom_check")`) and optionally with `deploy=True` if it should run in only in deploy mode
+- Preflight results should use `PreflightResult` (optionally with `warning=True`) instead of `preflight.Warning` or `preflight.Error`
+- Preflight result IDs should be descriptive strings (e.g., `models.lazy_reference_resolution_failed`) instead of numeric codes
+- `PREFLIGHT_SILENCED_CHECKS` setting has been replaced with `PREFLIGHT_SILENCED_RESULTS` which should contain a list of result IDs to silence. `PREFLIGHT_SILENCED_CHECKS` now silences entire checks by name.
+
+## [0.67.0](https://github.com/dropseed/plain/releases/plain@0.67.0) (2025-09-22)
+
+### What's changed
+
+- `ALLOWED_HOSTS` now defaults to `[]` (empty list) which allows all hosts, making it easier for development setups ([d3cb7712b9](https://github.com/dropseed/plain/commit/d3cb7712b9))
+- Empty `ALLOWED_HOSTS` in production now triggers a preflight error instead of a warning to ensure proper security configuration ([d3cb7712b9](https://github.com/dropseed/plain/commit/d3cb7712b9))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.66.0](https://github.com/dropseed/plain/releases/plain@0.66.0) (2025-09-22)
 
 ### What's changed

{plain-0.66.0 → plain-0.68.0}/plain/chores/registry.py

@@ -1,6 +1,3 @@
-from importlib import import_module
-from importlib.util import find_spec
-
 from plain.packages import packages_registry
 
 
@@ -35,21 +32,7 @@ class ChoresRegistry:
         """
         Import modules from installed packages and app to trigger registration.
         """
-        # Import from installed packages
-        for package_config in packages_registry.get_package_configs():
-            import_name = f"{package_config.name}.chores"
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
-
-        # Import from app
-        import_name = "app.chores"
-        if find_spec(import_name):
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
+        packages_registry.autodiscover_modules("chores", include_app=True)
 
     def get_chores(self):
         """

plain-0.68.0/plain/cli/agent/request.py

@@ -0,0 +1,172 @@
+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
+
+        # 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.query.get(id=user_id)
+                    client.force_login(user)
+                    click.secho(
+                        f"Authenticated as user {user_id}", fg="green", dim=True
+                    )
+                except User.DoesNotExist:
+                    click.secho(f"User {user_id} not found", fg="red", err=True)
+                    return
+
+            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)
+
+    except Exception as e:
+        click.secho(f"Request failed: {e}", fg="red", err=True)

{plain-0.66.0 → plain-0.68.0}/plain/cli/core.py

@@ -13,7 +13,7 @@ from .chores import chores
 from .docs import docs
 from .formatting import PlainContext
 from .install import install
-from .preflight import preflight_checks
+from .preflight import preflight_cli
 from .registry import cli_registry
 from .scaffold import create
 from .settings import setting
@@ -30,7 +30,7 @@ def plain_cli():
 
 plain_cli.add_command(agent)
 plain_cli.add_command(docs)
-plain_cli.add_command(preflight_checks)
+plain_cli.add_command(preflight_cli)
 plain_cli.add_command(create)
 plain_cli.add_command(chores)
 plain_cli.add_command(build)

plain-0.68.0/plain/cli/preflight.py

@@ -0,0 +1,247 @@
+import json
+import sys
+
+import click
+
+from plain import preflight
+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")
+@click.option(
+    "--deploy",
+    is_flag=True,
+    help="Check deployment settings.",
+)
+@click.option(
+    "--format",
+    default="text",
+    type=click.Choice(["text", "json"]),
+    help="Output format (default: text)",
+)
+@click.option(
+    "--quiet",
+    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.
+    """
+    # 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)
+
+    total_checks = 0
+    passed_checks = 0
+    check_results = []
+
+    # Run checks and collect results
+    for check_class, check_name, issues in preflight.run_checks(
+        include_deploy_checks=deploy,
+    ):
+        total_checks += 1
+
+        # Filter out silenced issues
+        visible_issues = [issue for issue in issues if not issue.is_silenced()]
+
+        # For text format, show real-time progress
+        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)
+
+            # Determine status icon based on issue severity
+            if not visible_issues:
+                # No issues - passed
+                if not quiet:
+                    click.secho("✔", fg="green", err=True)
+                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)
+                    else:
+                        click.secho("⚠", fg="yellow", err=True)
+
+                # Print issues with simple indentation
+                issues_to_show = (
+                    visible_issues
+                    if not quiet
+                    else [issue for issue in visible_issues if not issue.warning]
+                )
+                for i, issue in enumerate(issues_to_show):
+                    issue_color = "red" if not issue.warning else "yellow"
+                    issue_type = "ERROR" if not issue.warning else "WARNING"
+
+                    if quiet:
+                        # In quiet mode, show check name once, then issues
+                        if i == 0:
+                            click.secho(f"{check_name}:", err=True)
+                        # Show ID and fix on separate lines with same indentation
+                        click.secho(
+                            f"  [{issue_type}] {issue.id}:",
+                            fg=issue_color,
+                            bold=True,
+                            err=True,
+                            nl=False,
+                        )
+                        click.secho(f" {issue.fix}", err=True, 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,
+                            nl=False,
+                        )
+                        click.secho(f"{issue.fix}", err=True, dim=True)
+        else:
+            # For JSON format, just count passed checks
+            if not visible_issues:
+                passed_checks += 1
+
+        check_results.append((check_class, check_name, issues))
+
+    # Output results based on format
+
+    # Get all issues from check_results instead of maintaining separate list
+    all_issues = [issue for _, _, issues in check_results for issue in issues]
+    # Errors (non-warnings) cause preflight to fail
+    has_errors = any(
+        not issue.warning and not issue.is_silenced() for issue in all_issues
+    )
+
+    if format == "json":
+        # Build JSON output
+        results = {"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 = {
+                "name": check_name,
+                "passed": len(visible_issues) == 0,
+                "issues": [],
+            }
+
+            for issue in visible_issues:
+                issue_data = {
+                    "id": issue.id,
+                    "warning": issue.warning,
+                    "fix": issue.fix,
+                    "obj": str(issue.obj) if issue.obj is not None else None,
+                }
+                check_result["issues"].append(issue_data)
+
+            results["checks"].append(check_result)
+
+        click.echo(json.dumps(results, indent=2))
+    else:
+        # Text format summary
+        if not quiet:
+            click.echo()
+
+        # Calculate warning and error counts
+        warning_count = sum(
+            1
+            for _, _, issues in check_results
+            if issues
+            and not any(
+                not issue.warning for issue in issues if not issue.is_silenced()
+            )
+        )
+        error_count = sum(
+            1
+            for _, _, issues in check_results
+            if issues
+            and any(not issue.warning for issue in issues if not issue.is_silenced())
+        )
+
+        # Build colored summary parts
+        summary_parts = []
+
+        if passed_checks > 0:
+            summary_parts.append(click.style(f"{passed_checks} passed", fg="green"))
+
+        if warning_count > 0:
+            summary_parts.append(click.style(f"{warning_count} warnings", fg="yellow"))
+
+        if error_count > 0:
+            summary_parts.append(click.style(f"{error_count} errors", fg="red"))
+
+        # Show checkmark if successful (no errors)
+        if not has_errors:
+            icon = click.style("✔ ", fg="green")
+            summary_color = "green"
+        else:
+            icon = ""
+            summary_color = None
+
+        summary_text = ", ".join(summary_parts) if summary_parts else "no issues"
+
+        click.secho(f"{icon}{summary_text}", fg=summary_color, err=True)
+
+    # 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-0.66.0 → plain-0.68.0}/plain/cli/registry.py

@@ -1,6 +1,3 @@
-from importlib import import_module
-from importlib.util import find_spec
-
 from plain.packages import packages_registry
 
 
@@ -18,21 +15,7 @@ class CLIRegistry:
         """
         Import modules from installed packages and app to trigger registration.
         """
-        # Import from installed packages
-        for package_config in packages_registry.get_package_configs():
-            import_name = f"{package_config.name}.cli"
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
-
-        # Import from app
-        import_name = "app.cli"
-        if find_spec(import_name):
-            try:
-                import_module(import_name)
-            except ModuleNotFoundError:
-                pass
+        packages_registry.autodiscover_modules("cli", include_app=True)
 
     def get_commands(self):
         """

{plain-0.66.0 → plain-0.68.0}/plain/internal/middleware/hosts.py

@@ -159,7 +159,6 @@ def validate_host(host: str, allowed_hosts: list[str]) -> bool:
     Check that the host looks valid and matches a host or host pattern in the
     given list of ``allowed_hosts``. Supported patterns:
 
-    - ``*`` matches anything
     - ``.example.com`` matches a domain and all its subdomains
       (e.g. ``example.com`` and ``sub.example.com``)
     - ``example.com`` matches exactly that domain
@@ -176,10 +175,6 @@ def validate_host(host: str, allowed_hosts: list[str]) -> bool:
     host_ip = parse_ip_address(host)
 
     for pattern in allowed_hosts:
-        # Wildcard matches everything
-        if pattern == "*":
-            return True
-
         # Check CIDR notation patterns using walrus operator
         if network := parse_cidr_pattern(pattern):
             if host_ip and host_ip in network:

{plain-0.66.0 → plain-0.68.0}/plain/packages/registry.py

@@ -2,6 +2,7 @@ import sys
 import threading
 from collections import Counter
 from importlib import import_module
+from importlib.util import find_spec
 
 from plain.exceptions import ImproperlyConfigured, PackageRegistryNotReady
 
@@ -188,6 +189,19 @@ class PackagesRegistry:
 
         return package_config
 
+    def autodiscover_modules(self, module_name: str, *, include_app: bool) -> None:
+        def _import_if_exists(name):
+            if find_spec(name):
+                import_module(name)
+
+        # Load from all packages
+        for package_config in self.get_package_configs():
+            _import_if_exists(f"{package_config.name}.{module_name}")
+
+        # Load from app if requested
+        if include_app:
+            _import_if_exists(f"app.{module_name}")
+
 
 packages_registry = PackagesRegistry(installed_packages=None)
 

{plain-0.66.0 → plain-0.68.0}/plain/preflight/README.md

@@ -13,7 +13,7 @@
 Preflight checks help identify issues with your settings or environment before running your application.
 
 ```bash
-plain preflight
+plain preflight check
 ```
 
 ## Development
@@ -22,10 +22,10 @@ If you use [`plain.dev`](/plain-dev/README.md) for local development, the Plain
 
 ## Deployment
 
-The `plain preflight` command should often be part of your deployment process. Make sure to add the `--deploy` flag to the command to run checks that are only relevant in a production environment.
+The `plain preflight check` command should often be part of your deployment process. Make sure to add the `--deploy` flag to the command to run checks that are only relevant in a production environment.
 
 ```bash
-plain preflight --deploy
+plain preflight check --deploy
 ```
 
 ## Custom preflight checks
@@ -51,11 +51,11 @@ def custom_deploy_check(package_configs, **kwargs):
 
 ## Silencing preflight checks
 
-The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.W020`).
+The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.E020`).
 
 ```python
 # app/settings.py
 PREFLIGHT_SILENCED_CHECKS = [
-    "security.W020",
+    "security.E020",  # Allow empty ALLOWED_HOSTS in deployment
 ]
 ```

plain-0.68.0/plain/preflight/__init__.py

@@ -0,0 +1,16 @@
+from .checks import PreflightCheck
+from .registry import register_check, run_checks
+from .results import PreflightResult
+
+# Import these to force registration of checks
+import plain.preflight.files  # NOQA isort:skip
+import plain.preflight.security  # NOQA isort:skip
+import plain.preflight.urls  # NOQA isort:skip
+
+
+__all__ = [
+    "PreflightCheck",
+    "PreflightResult",
+    "register_check",
+    "run_checks",
+]

plain-0.68.0/plain/preflight/checks.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+
+
+class PreflightCheck(ABC):
+    """Base class for all preflight checks."""
+
+    @abstractmethod
+    def run(self):
+        """Must return a list of Warning/Error results."""
+        raise NotImplementedError

plain-0.68.0/plain/preflight/files.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from plain.runtime import settings
+
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
+
+
+@register_check("files.upload_temp_dir")
+class CheckSettingFileUploadTempDir(PreflightCheck):
+    """Validates that the FILE_UPLOAD_TEMP_DIR setting points to an existing directory."""
+
+    def run(self):
+        setting = settings.FILE_UPLOAD_TEMP_DIR
+        if setting and not Path(setting).is_dir():
+            return [
+                PreflightResult(
+                    fix=f"FILE_UPLOAD_TEMP_DIR points to nonexistent directory '{setting}'. Create the directory or update the setting.",
+                    id="files.upload_temp_dir_nonexistent",
+                )
+            ]
+        return []