Add Secret type, configurable env prefixes, and settings CLI

- Add Secret[T] type annotation for masking sensitive settings
- Add ENV_SETTINGS_PREFIXES setting for configurable env var prefixes
- Add preflight check for unused env vars matching configured prefixes
- Add `plain settings list` and `plain settings get` CLI commands
- Show env-loaded settings on server startup
- Track which env var provided each setting (env_var_name)

Author: davegaeddert

plain/plain/cli/core.py

@@ -20,7 +20,7 @@
 from .registry import cli_registry
 from .scaffold import create
 from .server import server
-from .settings import setting
+from .settings import settings
 from .shell import run, shell
 from .upgrade import upgrade
 from .urls import urls
@@ -41,7 +41,7 @@ def plain_cli() -> None:
 plain_cli.add_command(utils)
 plain_cli.add_command(urls)
 plain_cli.add_command(changelog)
-plain_cli.add_command(setting)
+plain_cli.add_command(settings)
 plain_cli.add_command(shell)
 plain_cli.add_command(run)
 plain_cli.add_command(install)

plain/plain/cli/server.py

@@ -111,6 +111,16 @@ def server(
     pidfile: str | None,
 ) -> None:
     """Production-ready WSGI server"""
+    from plain.runtime import settings
+
+    # Show settings loaded from environment
+    if env_settings := settings.get_env_settings():
+        click.secho("Settings from env:", dim=True)
+        for name, defn in env_settings:
+            click.secho(
+                f"  {defn.env_var_name} -> {name}={defn.display_value()}", dim=True
+            )
+
     from plain.server import ServerApplication
     from plain.server.config import Config
 

plain/plain/cli/settings.py

@@ -3,58 +3,62 @@
 import plain.runtime
 
 
-@click.command()
+@click.group()
+def settings() -> None:
+    """View and inspect settings"""
+    pass
+
+
+@settings.command()
 @click.argument("setting_name")
-def setting(setting_name: str) -> None:
-    """Print the value of a setting at runtime"""
+def get(setting_name: str) -> None:
+    """Get the value of a specific setting"""
     try:
-        setting = getattr(plain.runtime.settings, setting_name)
-        click.echo(setting)
+        value = getattr(plain.runtime.settings, setting_name)
+        click.echo(value)
     except AttributeError:
         click.secho(f'Setting "{setting_name}" not found', fg="red")
 
 
-# @plain_cli.command()
-# @click.option("--filter", "-f", "name_filter", help="Filter settings by name")
-# @click.option("--overridden", is_flag=True, help="Only show overridden settings")
-# def settings(name_filter, overridden):
-#     """Print Plain settings"""
-#     table = Table(box=box.MINIMAL)
-#     table.add_column("Setting")
-#     table.add_column("Default value")
-#     table.add_column("App value")
-#     table.add_column("Type")
-#     table.add_column("Module")
-
-#     for setting in dir(settings):
-#         if setting.isupper():
-#             if name_filter and name_filter.upper() not in setting:
-#                 continue
-
-#             is_overridden = settings.is_overridden(setting)
-
-#             if overridden and not is_overridden:
-#                 continue
-
-#             default_setting = settings._default_settings.get(setting)
-#             if default_setting:
-#                 default_value = default_setting.value
-#                 annotation = default_setting.annotation
-#                 module = default_setting.module
-#             else:
-#                 default_value = ""
-#                 annotation = ""
-#                 module = ""
-
-#             table.add_row(
-#                 setting,
-#                 Pretty(default_value) if default_value else "",
-#                 Pretty(getattr(settings, setting))
-#                 if is_overridden
-#                 else Text("<Default>", style="italic dim"),
-#                 Pretty(annotation) if annotation else "",
-#                 str(module.__name__) if module else "",
-#             )
-
-#     console = Console()
-#     console.print(table)
+@settings.command(name="list")
+def list_settings() -> None:
+    """List all settings with their sources"""
+    if not (items := plain.runtime.settings.get_settings()):
+        click.echo("No settings configured.")
+        return
+
+    # Calculate column widths
+    max_name = max(len(name) for name, _ in items)
+    max_source = max(len(defn.env_var_name or defn.source) for _, defn in items)
+
+    # Print header
+    header = (
+        click.style(f"{'Setting':<{max_name}}", bold=True)
+        + "  "
+        + click.style(f"{'Source':<{max_source}}", bold=True)
+        + "  "
+        + click.style("Value", bold=True)
+    )
+    click.echo(header)
+    click.secho("-" * (max_name + max_source + 10), dim=True)
+
+    # Print each setting
+    for name, defn in items:
+        source_info = defn.env_var_name or defn.source
+        value = defn.display_value()
+
+        # Style based on source
+        if defn.source == "env":
+            source_styled = click.style(f"{source_info:<{max_source}}", fg="green")
+        elif defn.source == "explicit":
+            source_styled = click.style(f"{source_info:<{max_source}}", fg="cyan")
+        else:
+            source_styled = click.style(f"{source_info:<{max_source}}", dim=True)
+
+        # Style secret values
+        if defn.is_secret:
+            value_styled = click.style(value, dim=True)
+        else:
+            value_styled = value
+
+        click.echo(f"{name:<{max_name}}  {source_styled}  {value_styled}")

plain/plain/preflight/__init__.py

@@ -5,6 +5,7 @@
 # Import these to force registration of checks
 import plain.preflight.files  # NOQA isort:skip
 import plain.preflight.security  # NOQA isort:skip
+import plain.preflight.settings  # NOQA isort:skip
 import plain.preflight.urls  # NOQA isort:skip
 
 

plain/plain/preflight/settings.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+
+from plain.runtime import settings
+
+from .checks import PreflightCheck
+from .registry import register_check
+from .results import PreflightResult
+
+
+@register_check(name="settings.unused_env_vars")
+class CheckUnusedEnvVars(PreflightCheck):
+    """Detect environment variables that look like settings but aren't used."""
+
+    def run(self) -> list[PreflightResult]:
+        results: list[PreflightResult] = []
+
+        # Get all env vars matching any configured prefix
+        for prefix in settings._env_prefixes:
+            for key in os.environ:
+                if key.startswith(prefix) and key.isupper():
+                    setting_name = key[len(prefix) :]
+                    # Skip empty setting names (just the prefix itself)
+                    if setting_name and setting_name not in settings._settings:
+                        results.append(
+                            PreflightResult(
+                                fix=f"Environment variable '{key}' looks like a setting but "
+                                f"'{setting_name}' is not a recognized setting.",
+                                id="settings.unused_env_var",
+                                warning=True,
+                            )
+                        )
+
+        # Warn if PLAIN_ env vars exist but PLAIN_ not in prefixes
+        if "PLAIN_" not in settings._env_prefixes:
+            plain_vars = [
+                k
+                for k in os.environ
+                if k.startswith("PLAIN_")
+                and k.isupper()
+                and k != "PLAIN_SETTINGS_MODULE"  # This one is always valid
+            ]
+            if plain_vars:
+                results.append(
+                    PreflightResult(
+                        fix=f"Found PLAIN_ environment variables but 'PLAIN_' is not in "
+                        f"ENV_SETTINGS_PREFIXES: {', '.join(sorted(plain_vars))}",
+                        id="settings.plain_prefix_disabled",
+                        warning=True,
+                    )
+                )
+
+        return results

plain/plain/runtime/__init__.py

@@ -7,6 +7,7 @@
 from plain.logs.configure import configure_logging
 from plain.packages import packages_registry
 
+from .secret import Secret
 from .user_settings import Settings
 
 try:
@@ -90,6 +91,7 @@ def __init__(self, setting_name: str):
 __all__ = [
     "setup",
     "settings",
+    "Secret",
     "SettingsReference",
     "APP_PATH",
     "__version__",

plain/plain/runtime/global_settings.py

@@ -3,6 +3,7 @@
 by the PLAIN_SETTINGS_MODULE environment variable.
 """
 
+from .secret import Secret
 from .utils import get_app_info_from_pyproject
 
 # MARK: Core Settings
@@ -18,6 +19,12 @@
 
 URLS_ROUTER: str
 
+# List of environment variable prefixes to check for settings.
+# Settings can be configured via environment variables using these prefixes.
+# Example: ENV_SETTINGS_PREFIXES = ["PLAIN_", "MYAPP_"]
+# Then both PLAIN_DEBUG and MYAPP_DEBUG would set the DEBUG setting.
+ENV_SETTINGS_PREFIXES: list[str] = ["PLAIN_"]
+
 # MARK: HTTP and Security
 
 # Hosts/domain names that are valid for this site.
@@ -66,11 +73,11 @@
 # A secret key for this particular Plain installation. Used in secret-key
 # hashing algorithms. Set this in your settings, or Plain will complain
 # loudly.
-SECRET_KEY: str
+SECRET_KEY: Secret[str]
 
 # List of secret keys used to verify the validity of signatures. This allows
 # secret key rotation.
-SECRET_KEY_FALLBACKS: list[str] = []
+SECRET_KEY_FALLBACKS: Secret[list[str]] = []  # type: ignore[assignment]
 
 # MARK: Internationalization
 

plain/plain/runtime/secret.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Secret(Generic[T]):
+    """
+    Marker type for sensitive settings. Values are masked in output/logs.
+
+    Usage:
+        SECRET_KEY: Secret[str]
+        DATABASE_PASSWORD: Secret[str]
+
+    At runtime, the value is still a plain str - this is purely for
+    indicating that the setting should be masked when displayed.
+    """
+
+    pass