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

plain/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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/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/cli/preflight.py

@@ -1,126 +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
 
 
-@click.command("preflight")
-@click.argument("package_label", nargs=-1)
+@preflight_cli.command("check")
 @click.option(
     "--deploy",
     is_flag=True,
     help="Check deployment settings.",
 )
 @click.option(
-    "--fail-level",
-    default="ERROR",
-    type=click.Choice(["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"]),
-    help="Message level that will cause the command to exit with a non-zero status. Default is ERROR.",
+    "--format",
+    default="text",
+    type=click.Choice(["text", "json"]),
+    help="Output format (default: text)",
 )
 @click.option(
-    "--database",
+    "--quiet",
     is_flag=True,
-    help="Run database related checks as part of preflight.",
+    help="Hide progress output and warnings, only show errors.",
 )
-def preflight_checks(package_label, deploy, fail_level, database):
+def check_command(deploy, format, quiet):
     """
     Use the system check framework to validate entire Plain project.
-    Raise CommandError for any serious message (error or critical errors).
-    If there are only light messages (like warnings), print them to stderr
-    and don't raise an exception.
+    Exit with error code if any errors are found. Warnings do not cause failure.
     """
-    include_deployment_checks = deploy
+    # Auto-discover and load preflight checks
+    packages_registry.autodiscover_modules("preflight", include_app=True)
 
-    if package_label:
-        package_configs = [
-            packages_registry.get_package_config(label) for label in package_label
-        ]
-    else:
-        package_configs = None
+    if not quiet:
+        click.secho("Running preflight checks...", dim=True, italic=True, err=True)
 
-    all_issues = preflight.run_checks(
-        package_configs=package_configs,
-        include_deployment_checks=include_deployment_checks,
-        database=database,
-    )
+    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)
 
-    header, body, footer = "", "", ""
-    visible_issue_count = 0  # excludes silenced warnings
-
-    if all_issues:
-        debugs = [
-            e for e in all_issues if e.level < preflight.INFO and not e.is_silenced()
-        ]
-        infos = [
-            e
-            for e in all_issues
-            if preflight.INFO <= e.level < preflight.WARNING and not e.is_silenced()
-        ]
-        warnings = [
-            e
-            for e in all_issues
-            if preflight.WARNING <= e.level < preflight.ERROR and not e.is_silenced()
-        ]
-        errors = [
-            e
-            for e in all_issues
-            if preflight.ERROR <= e.level < preflight.CRITICAL and not e.is_silenced()
-        ]
-        criticals = [
-            e
-            for e in all_issues
-            if preflight.CRITICAL <= e.level and not e.is_silenced()
-        ]
-        sorted_issues = [
-            (criticals, "CRITICALS"),
-            (errors, "ERRORS"),
-            (warnings, "WARNINGS"),
-            (infos, "INFOS"),
-            (debugs, "DEBUGS"),
-        ]
-
-        for issues, group_name in sorted_issues:
-            if issues:
-                visible_issue_count += len(issues)
-                formatted = (
-                    click.style(str(e), fg="red")
-                    if e.is_serious()
-                    else click.style(str(e), fg="yellow")
-                    for e in issues
+            # 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]
                 )
-                formatted = "\n".join(sorted(formatted))
-                body += f"\n{group_name}:\n{formatted}\n"
+                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 visible_issue_count:
-        header = "Preflight check identified some issues:\n"
+                    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
 
-    if any(
-        e.is_serious(getattr(preflight, fail_level)) and not e.is_silenced()
-        for e in all_issues
-    ):
-        footer += "\n"
-        footer += "Preflight check identified {} ({} silenced).".format(
-            "no issues"
-            if visible_issue_count == 0
-            else "1 issue"
-            if visible_issue_count == 1
-            else f"{visible_issue_count} issues",
-            len(all_issues) - visible_issue_count,
-        )
-        msg = click.style(f"SystemCheckError: {header}", fg="red") + body + footer
-        raise click.ClickException(msg)
+        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:
-        if visible_issue_count:
-            footer += "\n"
-            footer += "Preflight check identified {} ({} silenced).".format(
-                "no issues"
-                if visible_issue_count == 0
-                else "1 issue"
-                if visible_issue_count == 1
-                else f"{visible_issue_count} issues",
-                len(all_issues) - visible_issue_count,
+        # 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()
             )
-            msg = header + body + footer
-            click.echo(msg, err=True)
+        )
+        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:
-            click.secho("✔ Checks passed", err=True, fg="green")
+            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/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/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/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/preflight/__init__.py

@@ -1,17 +1,6 @@
-from .messages import (
-    CRITICAL,
-    DEBUG,
-    ERROR,
-    INFO,
-    WARNING,
-    CheckMessage,
-    Critical,
-    Debug,
-    Error,
-    Info,
-    Warning,
-)
+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
@@ -20,17 +9,8 @@ import plain.preflight.urls  # NOQA isort:skip
 
 
 __all__ = [
-    "CheckMessage",
-    "Debug",
-    "Info",
-    "Warning",
-    "Error",
-    "Critical",
-    "DEBUG",
-    "INFO",
-    "WARNING",
-    "ERROR",
-    "CRITICAL",
+    "PreflightCheck",
+    "PreflightResult",
     "register_check",
     "run_checks",
 ]

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/preflight/files.py

@@ -2,18 +2,22 @@ from pathlib import Path
 
 from plain.runtime import settings
 
-from . import Error, register_check
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
 
 
-@register_check
-def check_setting_file_upload_temp_dir(package_configs, **kwargs):
-    setting = getattr(settings, "FILE_UPLOAD_TEMP_DIR", None)
-    if setting and not Path(setting).is_dir():
-        return [
-            Error(
-                f"The FILE_UPLOAD_TEMP_DIR setting refers to the nonexistent "
-                f"directory '{setting}'.",
-                id="files.E001",
-            ),
-        ]
-    return []
+@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 []