plain 0.78.1__tar.gz → 0.88.0__tar.gz

{plain-0.78.1 → plain-0.88.0}/.gitignore

@@ -1,5 +1,5 @@
 .venv
-.env
+/.env
 *.egg-info
 *.py[co]
 __pycache__
@@ -8,8 +8,8 @@ __pycache__
 # Test apps
 plain*/tests/.plain
 
-# Ottobot
-.aider*
+# Agent scratch files
+/scratch
 
 # Plain temp dirs
 .plain

{plain-0.78.1 → plain-0.88.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.78.1
+Version: 0.88.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
 License-File: LICENSE
 Requires-Python: >=3.13
 Requires-Dist: click>=8.0.0

{plain-0.78.1 → plain-0.88.0}/plain/CHANGELOG.md

@@ -1,5 +1,206 @@
 # plain changelog
 
+## [0.88.0](https://github.com/dropseed/plain/releases/plain@0.88.0) (2025-11-13)
+
+### What's changed
+
+- The `plain.forms` module now uses explicit imports instead of wildcard imports, improving IDE autocomplete and type checking support ([eff36f3](https://github.com/dropseed/plain/commit/eff36f31e8e15f84e11164a44c833aeab096ffbd))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.87.0](https://github.com/dropseed/plain/releases/plain@0.87.0) (2025-11-12)
+
+### What's changed
+
+- Internal classes now use abstract base classes with `@abstractmethod` decorators instead of raising `NotImplementedError`, improving type checking and IDE support ([91b329a](https://github.com/dropseed/plain/commit/91b329a8adb477031c4358e638b12f35f19bb85d), [81b5f88](https://github.com/dropseed/plain/commit/81b5f88a4bd39785f6b19c3c00c0ed23a36fb72f), [d2e2423](https://github.com/dropseed/plain/commit/d2e24235f497a92f45d5a21fc83d802897c2dec0), [61e7b5a](https://github.com/dropseed/plain/commit/61e7b5a0c8675aaaf65f0a626ff7959a786dca7f))
+- Updated to latest version of `ty` type checker and fixed type errors and warnings throughout the codebase ([f4dbcef](https://github.com/dropseed/plain/commit/f4dbcefa929058be517cb1d4ab35bd73a89f26b8))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.86.2](https://github.com/dropseed/plain/releases/plain@0.86.2) (2025-11-11)
+
+### What's changed
+
+- CLI color output is now enabled in CI environments by checking the `CI` environment variable, matching the behavior of modern tools like uv ([a1500f15ed](https://github.com/dropseed/plain/commit/a1500f15ed))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.86.1](https://github.com/dropseed/plain/releases/plain@0.86.1) (2025-11-10)
+
+### What's changed
+
+- The `plain preflight` command now outputs to stderr only when using `--format json`, keeping stdout clean for JSON parsing while avoiding success messages appearing in error logs for text format ([72ebee7729](https://github.com/dropseed/plain/commit/72ebee7729))
+- CLI color handling now follows the CLICOLOR standard with proper priority: `NO_COLOR` > `CLICOLOR_FORCE`/`FORCE_COLOR` > `CLICOLOR` > `isatty` ([c7fea406c5](https://github.com/dropseed/plain/commit/c7fea406c5))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.86.0](https://github.com/dropseed/plain/releases/plain@0.86.0) (2025-11-10)
+
+### What's changed
+
+- Log output is now split by severity level: INFO and below go to stdout, WARNING and above go to stderr for proper cloud platform log classification ([52403b15ba](https://github.com/dropseed/plain/commit/52403b15ba))
+- Added `LOG_STREAM` setting to customize log output behavior with options: `"split"` (default), `"stdout"`, or `"stderr"` ([52403b15ba](https://github.com/dropseed/plain/commit/52403b15ba))
+- Log configuration documentation expanded with detailed guidance on output streams and environment variable settings ([52403b15ba](https://github.com/dropseed/plain/commit/52403b15ba))
+
+### Upgrade instructions
+
+- No changes required (default behavior splits logs to stdout/stderr automatically, but this can be customized via `PLAIN_LOG_STREAM` environment variable if needed)
+
+## [0.85.0](https://github.com/dropseed/plain/releases/plain@0.85.0) (2025-11-03)
+
+### What's changed
+
+- CLI help output now organizes commands into "Common Commands", "Core Commands", and "Package Commands" sections for better discoverability ([73d3a48](https://github.com/dropseed/plain/commit/73d3a48fca))
+- CLI help output has been customized with improved formatting and shortcut indicators showing which commands are shortcuts (e.g., `migrate → models migrate`) ([db882e6](https://github.com/dropseed/plain/commit/db882e6d47))
+- CSRF exception messages now include more detailed context about what was rejected and why (e.g., port mismatches, host mismatches) ([9a8e09c](https://github.com/dropseed/plain/commit/9a8e09c1dc))
+- The `plain agent md` command now saves a combined `AGENTS.md` file to `.plain/` by default when using `plain dev`, making it easier to provide context to coding agents ([786b7a0](https://github.com/dropseed/plain/commit/786b7a0ca1))
+- CLI help text styling has been refined with dimmed descriptions and usage prefixes for improved readability ([d7f7053](https://github.com/dropseed/plain/commit/d7f705398d))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.84.1](https://github.com/dropseed/plain/releases/plain@0.84.1) (2025-10-31)
+
+### What's changed
+
+- Added `license = "BSD-3-Clause"` to package metadata in `pyproject.toml` ([8477355](https://github.com/dropseed/plain/commit/8477355e65))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.84.0](https://github.com/dropseed/plain/releases/plain@0.84.0) (2025-10-29)
+
+### What's changed
+
+- The `DEFAULT_RESPONSE_HEADERS` setting now supports format string placeholders (e.g., `{request.csp_nonce}`) for dynamic header values instead of requiring a callable function ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Views can now set headers to `None` to explicitly remove default response headers ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Added comprehensive documentation for customizing default response headers including override, remove, and extend patterns ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+
+### Upgrade instructions
+
+- If you have `DEFAULT_RESPONSE_HEADERS` configured as a callable function, convert it to a dictionary with format string placeholders:
+
+    ```python
+    # Before:
+    def DEFAULT_RESPONSE_HEADERS(request):
+        nonce = request.csp_nonce
+        return {
+            "Content-Security-Policy": f"script-src 'self' 'nonce-{nonce}'",
+        }
+
+    # After:
+    DEFAULT_RESPONSE_HEADERS = {
+        "Content-Security-Policy": "script-src 'self' 'nonce-{request.csp_nonce}'",
+    }
+    ```
+
+- If you were overriding default headers to empty strings (`""`) to remove them, change those to `None` instead
+
+## [0.83.0](https://github.com/dropseed/plain/releases/plain@0.83.0) (2025-10-29)
+
+### What's changed
+
+- Added comprehensive Content Security Policy (CSP) documentation explaining how to use nonces with inline scripts and styles ([784f3dd972](https://github.com/dropseed/plain/commit/784f3dd972))
+- The `json_script` utility function now accepts an optional `nonce` parameter for CSP-compliant inline JSON scripts ([784f3dd972](https://github.com/dropseed/plain/commit/784f3dd972))
+
+### Upgrade instructions
+
+- Any `|json_script` usages need to make sure the second argument is a nonce, not a custom encoder (which is now third)
+
+## [0.82.0](https://github.com/dropseed/plain/releases/plain@0.82.0) (2025-10-29)
+
+### What's changed
+
+- The `DEFAULT_RESPONSE_HEADERS` setting can now be a callable that accepts a request argument, enabling dynamic header generation per request ([cb92905834](https://github.com/dropseed/plain/commit/cb92905834))
+- Added `request.csp_nonce` cached property for generating Content Security Policy nonces ([75071dcc70](https://github.com/dropseed/plain/commit/75071dcc70))
+- Simplified the preflight command by moving `plain preflight check` back to `plain preflight` ([40c2c4560e](https://github.com/dropseed/plain/commit/40c2c4560e))
+
+### Upgrade instructions
+
+- If you use `plain preflight check`, update to `plain preflight` (the `check` subcommand has been removed for simplicity)
+- If you use `plain preflight check --deploy`, update to `plain preflight --deploy`
+
+## [0.81.0](https://github.com/dropseed/plain/releases/plain@0.81.0) (2025-10-22)
+
+### What's changed
+
+- Removed support for category-specific error template fallbacks like `4xx.html` and `5xx.html` ([9513f7c4fa](https://github.com/dropseed/plain/commit/9513f7c4fa))
+
+### Upgrade instructions
+
+- If you have `4xx.html` or `5xx.html` error templates, rename them to specific status code templates (e.g., `404.html`, `500.html`) or remove them if you prefer the plain HTTP response fallback
+
+## [0.80.0](https://github.com/dropseed/plain/releases/plain@0.80.0) (2025-10-22)
+
+### What's changed
+
+- CSRF failures now raise `SuspiciousOperation` (HTTP 400) instead of `PermissionDenied` (HTTP 403) ([ad146bde3e](https://github.com/dropseed/plain/commit/ad146bde3e))
+- Error templates can now use category-specific fallbacks like `4xx.html` or `5xx.html` instead of the generic `error.html` ([716cfa3cfc](https://github.com/dropseed/plain/commit/716cfa3cfc))
+- Updated error template documentation with best practices for self-contained `500.html` templates ([55cea3b522](https://github.com/dropseed/plain/commit/55cea3b522))
+
+### Upgrade instructions
+
+- If you have a `templates/error.html` template, instead create specific error templates for each status code you want to customize (e.g., `400.html`, `403.html`, `404.html`, `500.html`). You can also create category-specific templates like `4xx.html` or `5xx.html` for broader coverage.
+
+## [0.79.0](https://github.com/dropseed/plain/releases/plain@0.79.0) (2025-10-22)
+
+### What's changed
+
+- Response objects now have an `exception` attribute that stores the exception that caused 5xx errors ([0a243ba89c](https://github.com/dropseed/plain/commit/0a243ba89c))
+- Middleware classes now use an abstract base class `HttpMiddleware` with a `process_request()` method ([b960eed6c6](https://github.com/dropseed/plain/commit/b960eed6c6))
+- CSRF middleware now raises `PermissionDenied` instead of rendering a custom `CsrfFailureView` ([d4b93e59b3](https://github.com/dropseed/plain/commit/d4b93e59b3))
+- The `HTTP_ERROR_VIEWS` setting has been removed ([7a4e3a31f4](https://github.com/dropseed/plain/commit/7a4e3a31f4))
+- Standalone `plain-changelog` and `plain-upgrade` executables have been removed in favor of the built-in commands ([07c3a4c540](https://github.com/dropseed/plain/commit/07c3a4c540))
+- Standalone `plain-build` executable has been removed ([99301ea797](https://github.com/dropseed/plain/commit/99301ea797))
+- Removed automatic logging of all HTTP 400+ status codes for cleaner logs ([c2769d7281](https://github.com/dropseed/plain/commit/c2769d7281))
+
+### Upgrade instructions
+
+- If you have custom middleware, inherit from `HttpMiddleware` and rename your `__call__()` method to `process_request()`:
+
+    ```python
+    # Before:
+    class MyMiddleware:
+        def __init__(self, get_response):
+            self.get_response = get_response
+
+        def __call__(self, request):
+            response = self.get_response(request)
+            return response
+
+    # After:
+    from plain.http import HttpMiddleware
+
+    class MyMiddleware(HttpMiddleware):
+        def process_request(self, request):
+            response = self.get_response(request)
+            return response
+    ```
+
+- Remove any custom `HTTP_ERROR_VIEWS` setting from your configuration - error views are now controlled entirely by exception handlers
+- If you were calling `plain-changelog` or `plain-upgrade` as standalone commands, use `plain changelog` or `plain upgrade` instead
+- If you were calling `plain-build` as a standalone command, use `plain build` instead
+
+## [0.78.2](https://github.com/dropseed/plain/releases/plain@0.78.2) (2025-10-20)
+
+### What's changed
+
+- Updated package metadata to use `[dependency-groups]` instead of `[tool.uv]` for development dependencies, following PEP 735 standard ([1b43a3a272](https://github.com/dropseed/plain/commit/1b43a3a272))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.78.1](https://github.com/dropseed/plain/releases/plain@0.78.1) (2025-10-17)
 
 ### What's changed

{plain-0.78.1 → plain-0.88.0}/plain/assets/views.py

@@ -14,6 +14,7 @@ from plain.http import (
     ResponseRedirect,
     StreamingResponse,
 )
+from plain.http.response import ResponseHeaders
 from plain.runtime import settings
 from plain.urls import reverse
 from plain.views import View
@@ -37,7 +38,7 @@ class AssetView(View):
     def get_url_path(self) -> str:
         return self.asset_path or self.url_kwargs["path"]
 
-    def get(self) -> Response | FileResponse:
+    def get(self) -> Response | FileResponse | StreamingResponse:
         url_path = self.get_url_path()
 
         # Make a trailing slash work, but we don't expect it
@@ -52,7 +53,11 @@ class AssetView(View):
                 if redirect_response := self.get_redirect_response(url_path):
                     return redirect_response
 
+        # check_asset_path validates and raises if path is invalid
+        # After this point, absolute_path is guaranteed to be a valid str
         self.check_asset_path(absolute_path)
+        # Type guard: absolute_path is now str (check_asset_path raises if None/invalid)
+        assert absolute_path is not None
 
         if encoded_path := self.get_encoded_path(absolute_path):
             absolute_path = encoded_path
@@ -127,7 +132,7 @@ class AssetView(View):
     def get_size(self, path: str) -> int:
         return os.path.getsize(path)
 
-    def update_headers(self, headers: dict, path: str) -> dict:
+    def update_headers(self, headers: ResponseHeaders, path: str) -> ResponseHeaders:
         headers.setdefault("Access-Control-Allow-Origin", "*")
 
         # Always vary on Accept-Encoding

plain-0.88.0/plain/cli/__init__.py

@@ -0,0 +1,4 @@
+from .registry import register_cli
+from .runtime import common_command
+
+__all__ = ["register_cli", "common_command"]

plain-0.88.0/plain/cli/agent/__init__.py

@@ -0,0 +1,17 @@
+import click
+
+from .docs import docs
+from .md import md
+from .request import request
+
+
+@click.group("agent")
+def agent() -> None:
+    """Tools for coding agents"""
+    pass
+
+
+# Add commands to the group
+agent.add_command(docs)
+agent.add_command(md)
+agent.add_command(request)

{plain-0.78.1 → plain-0.88.0}/plain/cli/agent/docs.py

@@ -16,7 +16,7 @@ from .llmdocs import LLMDocs
     help="List available packages",
 )
 def docs(package: str, show_list: bool) -> None:
-    """Show LLM-friendly documentation and source for a package."""
+    """Show LLM-friendly documentation for a package"""
 
     if show_list:
         # List available packages using same discovery logic as md command

plain-0.88.0/plain/cli/agent/md.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import importlib.util
+import pkgutil
+from pathlib import Path
+
+import click
+
+from plain.runtime import PLAIN_TEMP_PATH
+
+from ..output import iterate_markdown
+
+
+def _get_packages_with_agents() -> dict[str, Path]:
+    """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, check all search locations
+            for location in plain_spec.submodule_search_locations:
+                plain_path = Path(location)
+                agents_path = plain_path / "AGENTS.md"
+                if agents_path.exists():
+                    agents_files["plain"] = agents_path
+                    break  # Use the first one found
+
+        # Check other plain.* subpackages
+        if hasattr(plain, "__path__"):
+            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.option(
+    "--save",
+    default=None,
+    is_flag=False,
+    flag_value="PLAIN_TEMP_PATH",
+    help="Save combined AGENTS.md from all packages to file (default: .plain/AGENTS.md)",
+)
+def md(save: str | None) -> None:
+    """AGENTS.md from installed Plain packages"""
+
+    agents_files = _get_packages_with_agents()
+
+    if not agents_files:
+        return
+
+    # Handle --save flag
+    if save:
+        # Use PLAIN_TEMP_PATH if flag was used without value
+        if save == "PLAIN_TEMP_PATH":
+            save_path = PLAIN_TEMP_PATH / "AGENTS.md"
+        else:
+            save_path = Path(save)
+
+        # Check if we need to regenerate
+        if save_path.exists():
+            output_mtime = save_path.stat().st_mtime
+            # Check if any source file is newer
+            needs_regen = any(
+                path.stat().st_mtime > output_mtime for path in agents_files.values()
+            )
+            if not needs_regen:
+                return
+
+        # Ensure parent directory exists
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Generate combined file
+        with save_path.open("w") as f:
+            for pkg_name in sorted(agents_files.keys()):
+                content = agents_files[pkg_name].read_text()
+                f.write(content)
+                if not content.endswith("\n"):
+                    f.write("\n")
+                f.write("\n")
+    else:
+        # Display to console
+        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()

{plain-0.78.1 → plain-0.88.0}/plain/cli/agent/request.py

@@ -49,7 +49,7 @@ def request(
     content_type: str | None,
     headers: tuple[str, ...],
 ) -> None:
-    """Make an HTTP request using the test client against the development database."""
+    """Make an HTTP test request against the dev database"""
 
     try:
         # Only allow in DEBUG mode for security
@@ -98,7 +98,7 @@ def request(
 
         # Make the request
         method = method.upper()
-        kwargs: dict[str, object] = {
+        kwargs: dict[str, Any] = {
             "follow": follow,
         }
         if header_dict:

{plain-0.78.1 → plain-0.88.0}/plain/cli/build.py

@@ -34,7 +34,7 @@ from plain.assets.compile import compile_assets, get_compiled_path
     help="Compress the assets",
 )
 def build(keep_original: bool, fingerprint: bool, compress: bool) -> None:
-    """Pre-deployment build step (compile assets, css, js, etc.)"""
+    """Pre-deployment build step for assets and static files"""
 
     if not keep_original and not fingerprint:
         raise click.UsageError(

{plain-0.78.1 → plain-0.88.0}/plain/cli/changelog.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import click
 
 from .output import style_markdown
+from .runtime import without_runtime_setup
 
 
 def parse_version(version_str: str) -> tuple[int, ...]:
@@ -42,6 +43,7 @@ def compare_versions(v1: str, v2: str) -> int:
         return 0
 
 
+@without_runtime_setup
 @click.command("changelog")
 @click.argument("package_label")
 @click.option("--from", "from_version", help="Show entries from this version onwards")
@@ -49,7 +51,7 @@ def compare_versions(v1: str, v2: str) -> int:
 def changelog(
     package_label: str, from_version: str | None, to_version: str | None
 ) -> None:
-    """Show changelog entries for a package."""
+    """Show changelog for a package"""
     module_name = package_label.replace("-", ".")
     spec = find_spec(module_name)
     if not spec:

{plain-0.78.1 → plain-0.88.0}/plain/cli/chores.py

@@ -17,9 +17,7 @@ def chores() -> None:
     "--name", default=None, type=str, help="Name of the chore to run", multiple=True
 )
 def list_chores(name: tuple[str, ...]) -> None:
-    """
-    List all registered chores.
-    """
+    """List all registered chores"""
     from plain.chores.registry import chores_registry
 
     chores_registry.import_modules()
@@ -51,9 +49,7 @@ def list_chores(name: tuple[str, ...]) -> None:
     "--dry-run", is_flag=True, help="Show what would be done without executing"
 )
 def run_chores(name: tuple[str, ...], dry_run: bool) -> None:
-    """
-    Run the specified chores.
-    """
+    """Run specified chores"""
     from plain.chores.registry import chores_registry
 
     chores_registry.import_modules()

{plain-0.78.1 → plain-0.88.0}/plain/cli/core.py

@@ -140,5 +140,66 @@ class PlainCommandCollection(click.CommandCollection):
         self._ensure_registry_loaded()
         return super().list_commands(ctx)
 
+    def format_commands(self, ctx: Context, formatter: Any) -> None:
+        """Format commands with separate sections for common, core, and package commands."""
+        self._ensure_registry_loaded()
+
+        # Get all commands from both sources, tracking their source
+        commands = []
+        for source_index, source in enumerate(self.sources):
+            for name in source.list_commands(ctx):
+                cmd = source.get_command(ctx, name)
+                if cmd is not None:
+                    # source_index 0 = plain_cli (core), 1+ = registry (packages)
+                    commands.append((name, cmd, source_index))
+
+        if not commands:
+            return
+
+        # Get metadata from the registry (for shortcuts)
+        shortcuts_metadata = cli_registry.get_shortcuts()
+
+        # Separate commands into common, core, and package
+        common_commands = []
+        core_commands = []
+        package_commands = []
+
+        for name, cmd, source_index in commands:
+            help_text = cmd.get_short_help_str(limit=200)
+
+            # Check if command is marked as common via decorator
+            is_common = getattr(cmd, "is_common_command", False)
+
+            if is_common:
+                # This is a common command
+                # Add arrow notation if it's also a shortcut
+                if name in shortcuts_metadata:
+                    shortcut_for = shortcuts_metadata[name].shortcut_for
+                    if shortcut_for:
+                        alias_info = click.style(f"(→ {shortcut_for})", italic=True)
+                        help_text = f"{help_text} {alias_info}"
+                common_commands.append((name, help_text))
+            elif source_index == 0:
+                # Package command (from registry, inserted at index 0)
+                package_commands.append((name, help_text))
+            else:
+                # Core command (from plain_cli, at index 1)
+                core_commands.append((name, help_text))
+
+        # Write common commands section if any exist
+        if common_commands:
+            with formatter.section("Common Commands"):
+                formatter.write_dl(sorted(common_commands))
+
+        # Write core commands section if any exist
+        if core_commands:
+            with formatter.section("Core Commands"):
+                formatter.write_dl(sorted(core_commands))
+
+        # Write package commands section if any exist
+        if package_commands:
+            with formatter.section("Package Commands"):
+                formatter.write_dl(sorted(package_commands))
+
 
 cli = PlainCommandCollection()

{plain-0.78.1 → plain-0.88.0}/plain/cli/docs.py

@@ -10,6 +10,7 @@ from .output import iterate_markdown
 @click.option("--open", is_flag=True, help="Open the README in your default editor")
 @click.argument("module", default="")
 def docs(module: str, open: bool) -> None:
+    """Show documentation for a package"""
     if not module:
         raise click.UsageError(
             "You must specify a module. For LLM-friendly docs, use `plain agent docs`."

{plain-0.78.1 → plain-0.88.0}/plain/cli/formatting.py

@@ -9,17 +9,17 @@ from click.formatting import iter_rows, measure_table, term_len, wrap_text
 
 class PlainHelpFormatter(click.HelpFormatter):
     def write_heading(self, heading: str) -> None:
-        styled_heading = click.style(heading, underline=True)
+        styled_heading = click.style(heading, dim=True)
         self.write(f"{'':>{self.current_indent}}{styled_heading}\n")
 
     def write_usage(self, prog: str, args: str = "", prefix: str = "Usage: ") -> None:
-        prefix_styled = click.style(prefix, italic=True)
+        prefix_styled = click.style(prefix, dim=True)
         super().write_usage(prog, args, prefix=prefix_styled)
 
     def write_dl(
         self,
         rows: list[tuple[str, str]],
-        col_max: int = 30,
+        col_max: int = 20,
         col_spacing: int = 2,
     ) -> None:
         """Writes a definition list into the buffer.  This is how options
@@ -54,10 +54,15 @@ class PlainHelpFormatter(click.HelpFormatter):
             lines = wrapped_text.splitlines()
 
             if lines:
-                self.write(f"{lines[0]}\n")
+                # Dim the description text
+                first_line_styled = click.style(lines[0], dim=True)
+                self.write(f"{first_line_styled}\n")
 
                 for line in lines[1:]:
-                    self.write(f"{'':>{first_col + self.current_indent}}{line}\n")
+                    line_styled = click.style(line, dim=True)
+                    self.write(
+                        f"{'':>{first_col + self.current_indent}}{line_styled}\n"
+                    )
             else:
                 self.write("\n")
 
@@ -66,11 +71,24 @@ class PlainContext(click.Context):
     formatter_class = PlainHelpFormatter
 
     def __init__(self, *args: Any, **kwargs: Any):
+        # Set a wider max_content_width for help text (default is 80)
+        # This allows descriptions to fit more comfortably on one line
+        if "max_content_width" not in kwargs:
+            kwargs["max_content_width"] = 140
+
         super().__init__(*args, **kwargs)
 
-        # Force colors in CI environments
-        if any(
-            os.getenv(var)
-            for var in ["CI", "FORCE_COLOR", "GITHUB_ACTIONS", "GITLAB_CI"]
-        ) and not any(os.getenv(var) for var in ["NO_COLOR", "PYTEST_CURRENT_TEST"]):
+        # Follow CLICOLOR standard (http://bixense.com/clicolors/)
+        # Priority: NO_COLOR > CLICOLOR_FORCE/FORCE_COLOR > CI detection > CLICOLOR > isatty
+        if os.getenv("NO_COLOR") or os.getenv("PYTEST_CURRENT_TEST"):
+            self.color = False
+        elif os.getenv("CLICOLOR_FORCE") or os.getenv("FORCE_COLOR"):
+            self.color = True
+        elif os.getenv("CI"):
+            # Enable colors in CI/deployment environments even without TTY
+            # This matches behavior of modern tools like uv (via Rust's anstyle)
             self.color = True
+        elif os.getenv("CLICOLOR"):
+            # CLICOLOR=1 means use colors only if TTY (Click's default behavior)
+            pass  # Let Click handle it with isatty check
+        # Otherwise use Click's default behavior (isatty check)

{plain-0.78.1 → plain-0.88.0}/plain/cli/install.py

@@ -24,7 +24,7 @@ def install(
     agent_command: str | None = None,
     print_only: bool = False,
 ) -> None:
-    """Install Plain packages with the help of an agent."""
+    """Install Plain packages with agent assistance"""
     # Validate all package names
     invalid_packages = [pkg for pkg in packages if not pkg.startswith("plain")]
     if invalid_packages: