plain 0.67.0__tar.gz → 0.68.1__tar.gz

{plain-0.67.0 → plain-0.68.1}/PKG-INFO

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

{plain-0.67.0 → plain-0.68.1}/plain/CHANGELOG.md

@@ -1,5 +1,33 @@
 # plain changelog
 
+## [0.68.1](https://github.com/dropseed/plain/releases/plain@0.68.1) (2025-09-25)
+
+### What's changed
+
+- Preflight checks are now sorted by name for consistent ordering ([cb8e160](https://github.com/dropseed/plain/commit/cb8e160934))
+
+### Upgrade instructions
+
+- No changes required
+
+## [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
+
+- Update any uses of the `plain preflight` command to `plain preflight check`, and remove the `--database` and `--fail-level` options which no longer exist
+- 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

{plain-0.67.0 → plain-0.68.1}/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.67.0 → plain-0.68.1}/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.1/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.67.0 → plain-0.68.1}/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.67.0 → plain-0.68.1}/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.67.0 → plain-0.68.1}/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

plain-0.68.1/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.1/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.1/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 []

plain-0.68.1/plain/preflight/registry.py

@@ -0,0 +1,79 @@
+from plain.runtime import settings
+
+
+class CheckRegistry:
+    def __init__(self):
+        self.checks = {}  # name -> (check_class, deploy)
+
+    def register_check(self, check_class, name, deploy=False):
+        """Register a check class with a unique name."""
+        if name in self.checks:
+            raise ValueError(f"Check {name} already registered")
+        self.checks[name] = (check_class, deploy)
+
+    def run_checks(
+        self,
+        include_deploy_checks=False,
+    ):
+        """
+        Run all registered checks and yield (check_class, name, results) tuples.
+        """
+        # Validate silenced check names
+        silenced_checks = settings.PREFLIGHT_SILENCED_CHECKS
+        unknown_silenced = set(silenced_checks) - set(self.checks.keys())
+        if unknown_silenced:
+            unknown_names = ", ".join(sorted(unknown_silenced))
+            raise ValueError(
+                f"Unknown check names in PREFLIGHT_SILENCED_CHECKS: {unknown_names}. "
+                "Check for typos or remove outdated check names."
+            )
+
+        for name, (check_class, deploy) in sorted(self.checks.items()):
+            # Skip silenced checks
+            if name in silenced_checks:
+                continue
+
+            # Skip deployment checks if not requested
+            if deploy and not include_deploy_checks:
+                continue
+
+            # Instantiate and run check
+            check = check_class()
+            results = check.run()
+            yield check_class, name, results
+
+    def get_checks(self, include_deploy_checks=False):
+        """Get list of (check_class, name) tuples."""
+        result = []
+        for name, (check_class, deploy) in self.checks.items():
+            if deploy and not include_deploy_checks:
+                continue
+            result.append((check_class, name))
+        return result
+
+
+checks_registry = CheckRegistry()
+
+
+def register_check(name: str, *, deploy: bool = False):
+    """
+    Decorator to register a check class.
+
+    Usage:
+        @register_check("security.secret_key", deploy=True)
+        class CheckSecretKey(PreflightCheck):
+            pass
+
+        @register_check("files.upload_temp_dir")
+        class CheckUploadTempDir(PreflightCheck):
+            pass
+    """
+
+    def wrapper(cls):
+        checks_registry.register_check(cls, name=name, deploy=deploy)
+        return cls
+
+    return wrapper
+
+
+run_checks = checks_registry.run_checks

plain-0.68.1/plain/preflight/results.py

@@ -0,0 +1,29 @@
+from plain.runtime import settings
+
+
+class PreflightResult:
+    def __init__(self, *, fix: str, id: str, obj=None, warning: bool = False):
+        self.fix = fix
+        self.obj = obj
+        self.id = id
+        self.warning = warning
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and all(
+            getattr(self, attr) == getattr(other, attr)
+            for attr in ["fix", "obj", "id", "warning"]
+        )
+
+    def __str__(self):
+        if self.obj is None:
+            obj = ""
+        elif hasattr(self.obj, "_meta") and hasattr(self.obj._meta, "label"):
+            # Duck type for model objects - use their meta label
+            obj = self.obj._meta.label
+        else:
+            obj = str(self.obj)
+        id_part = f"({self.id}) " if self.id else ""
+        return f"{obj}: {id_part}{self.fix}"
+
+    def is_silenced(self):
+        return self.id and self.id in settings.PREFLIGHT_SILENCED_RESULTS

plain-0.68.1/plain/preflight/security.py

@@ -0,0 +1,81 @@
+from plain.runtime import settings
+
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
+
+SECRET_KEY_MIN_LENGTH = 50
+SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
+
+
+def _check_secret_key(secret_key):
+    return (
+        len(set(secret_key)) >= SECRET_KEY_MIN_UNIQUE_CHARACTERS
+        and len(secret_key) >= SECRET_KEY_MIN_LENGTH
+    )
+
+
+@register_check(name="security.secret_key", deploy=True)
+class CheckSecretKey(PreflightCheck):
+    """Validates that SECRET_KEY is long and random enough for security."""
+
+    def run(self):
+        if not _check_secret_key(settings.SECRET_KEY):
+            return [
+                PreflightResult(
+                    fix=f"SECRET_KEY is too weak (needs {SECRET_KEY_MIN_LENGTH}+ characters, "
+                    f"{SECRET_KEY_MIN_UNIQUE_CHARACTERS}+ unique). Generate a new long random value or "
+                    f"Plain's security features will be vulnerable to attack.",
+                    id="security.secret_key_weak",
+                )
+            ]
+        return []
+
+
+@register_check(name="security.secret_key_fallbacks", deploy=True)
+class CheckSecretKeyFallbacks(PreflightCheck):
+    """Validates that SECRET_KEY_FALLBACKS are long and random enough for security."""
+
+    def run(self):
+        errors = []
+        for index, key in enumerate(settings.SECRET_KEY_FALLBACKS):
+            if not _check_secret_key(key):
+                errors.append(
+                    PreflightResult(
+                        fix=f"SECRET_KEY_FALLBACKS[{index}] is too weak (needs {SECRET_KEY_MIN_LENGTH}+ characters, "
+                        f"{SECRET_KEY_MIN_UNIQUE_CHARACTERS}+ unique). Generate a new long random value or "
+                        f"Plain's security features will be vulnerable to attack.",
+                        id="security.secret_key_fallback_weak",
+                    )
+                )
+        return errors
+
+
+@register_check(name="security.debug", deploy=True)
+class CheckDebug(PreflightCheck):
+    """Ensures DEBUG is False in production deployment."""
+
+    def run(self):
+        if settings.DEBUG:
+            return [
+                PreflightResult(
+                    fix="DEBUG is True in deployment. Set DEBUG=False to prevent exposing sensitive information.",
+                    id="security.debug_enabled_in_production",
+                )
+            ]
+        return []
+
+
+@register_check(name="security.allowed_hosts", deploy=True)
+class CheckAllowedHosts(PreflightCheck):
+    """Ensures ALLOWED_HOSTS is not empty in production deployment."""
+
+    def run(self):
+        if not settings.ALLOWED_HOSTS:
+            return [
+                PreflightResult(
+                    fix="ALLOWED_HOSTS is empty in deployment. Add your domain(s) to prevent host header attacks.",
+                    id="security.allowed_hosts_empty",
+                )
+            ]
+        return []

plain-0.68.1/plain/preflight/urls.py

@@ -0,0 +1,13 @@
+from .checks import PreflightCheck
+from .registry import register_check
+
+
+@register_check("urls.config")
+class CheckUrlConfig(PreflightCheck):
+    """Validates the URL configuration for common issues."""
+
+    def run(self):
+        from plain.urls import get_resolver
+
+        resolver = get_resolver()
+        return resolver.preflight()