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

plain/chores/registry.py

@@ -1,42 +1,33 @@
-from plain.packages import packages_registry
-
+from __future__ import annotations
 
-class Chore:
-    def __init__(self, *, group, func):
-        self.group = group
-        self.func = func
-        self.name = f"{group}.{func.__name__}"
-        self.description = func.__doc__.strip() if func.__doc__ else ""
+from plain.packages import packages_registry
 
-    def __str__(self):
-        return self.name
-
-    def run(self):
-        """
-        Run the chore.
-        """
-        return self.func()
+from .core import Chore
 
 
 class ChoresRegistry:
-    def __init__(self):
-        self._chores = {}
+    def __init__(self) -> None:
+        self._chores: dict[str, type[Chore]] = {}
 
-    def register_chore(self, chore):
+    def register_chore(self, chore_class: type[Chore]) -> None:
         """
-        Register a chore with the specified name.
+        Register a chore class.
+
+        Args:
+            chore_class: A Chore subclass to register
         """
-        self._chores[chore.func] = chore
+        name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        self._chores[name] = chore_class
 
-    def import_modules(self):
+    def import_modules(self) -> None:
         """
         Import modules from installed packages and app to trigger registration.
         """
         packages_registry.autodiscover_modules("chores", include_app=True)
 
-    def get_chores(self):
+    def get_chores(self) -> list[type[Chore]]:
         """
-        Get all registered chores.
+        Get all registered chore classes.
         """
         return list(self._chores.values())
 
@@ -44,19 +35,15 @@ class ChoresRegistry:
 chores_registry = ChoresRegistry()
 
 
-def register_chore(group):
+def register_chore(cls: type[Chore]) -> type[Chore]:
     """
-    Register a chore with a given group.
+    Decorator to register a chore class.
 
     Usage:
-        @register_chore("clear_expired")
-        def clear_expired():
-            pass
+        @register_chore
+        class ClearExpired(Chore):
+            def run(self):
+                return "Done!"
     """
-
-    def wrapper(func):
-        chore = Chore(group=group, func=func)
-        chores_registry.register_chore(chore)
-        return func
-
-    return wrapper
+    chores_registry.register_chore(cls)
+    return cls

plain/cli/README.md

@@ -1,41 +1,210 @@
-# CLI
+# plain.cli
 
-**The `plain` CLI and how to add your own commands to it.**
+**The `plain` command-line interface and tools for adding custom commands.**
 
 - [Overview](#overview)
 - [Adding commands](#adding-commands)
+    - [Register a command group](#register-a-command-group)
+    - [Register a shortcut command](#register-a-shortcut-command)
+    - [Mark commands as common](#mark-commands-as-common)
+- [Shell](#shell)
+    - [Run a script with app context](#run-a-script-with-app-context)
+    - [SHELL_IMPORT](#shell_import)
+- [Built-in commands](#built-in-commands)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Commands are written using [Click](https://click.palletsprojects.com/en/8.1.x/)
-(one of Plain's few dependencies),
-which has been one of those most popular CLI frameworks in Python for a long time.
+The `plain` CLI provides commands for running your app, managing databases, starting shells, and more. You can also add your own commands using the [`register_cli`](./registry.py#register_cli) decorator.
 
-## Adding commands
-
-The [`register_cli`](./registry.py#register_cli) decorator can be used to add your own commands to the `plain` CLI.
+Commands are written using [Click](https://click.palletsprojects.com/), a popular Python CLI framework that is one of Plain's few dependencies.
 
 ```python
 import click
 from plain.cli import register_cli
 
 
-@register_cli("example-subgroup-name")
+@register_cli("hello")
+@click.command()
+def cli():
+    """Say hello"""
+    click.echo("Hello from my custom command!")
+```
+
+After defining this command, you can run it with `plain hello`:
+
+```bash
+$ plain hello
+Hello from my custom command!
+```
+
+## Adding commands
+
+You can register commands from anywhere, but Plain will automatically import `cli.py` modules from your app and installed packages. The most common locations are:
+
+- `app/cli.py` for app-specific commands
+- `<package>/cli.py` for package-specific commands
+
+### Register a command group
+
+Use [`@register_cli`](./registry.py#register_cli) with a Click group to create subcommands:
+
+```python
+@register_cli("users")
 @click.group()
 def cli():
-    """Custom example commands"""
+    """User management commands"""
     pass
 
+
+@cli.command()
+@click.argument("email")
+def create(email):
+    """Create a new user"""
+    click.echo(f"Creating user: {email}")
+
+
 @cli.command()
-def example_command():
-    click.echo("An example command!")
+def list():
+    """List all users"""
+    click.echo("Listing users...")
 ```
 
-Then you can run the command with `plain`.
+This creates `plain users create` and `plain users list` commands.
+
+### Register a shortcut command
+
+Some commands are used frequently enough to warrant a top-level shortcut. You can indicate that a command is a shortcut for a subcommand by passing `shortcut_for`:
+
+```python
+@register_cli("migrate", shortcut_for="models")
+@click.command()
+def migrate():
+    """Run database migrations"""
+    # ...
+```
+
+This makes `plain migrate` available as a shortcut for `plain models migrate`. The shortcut relationship is shown in help output.
+
+### Mark commands as common
+
+Use the [`common_command`](./runtime.py#common_command) decorator to highlight frequently used commands in help output:
+
+```python
+from plain.cli import register_cli
+from plain.cli.runtime import common_command
+
+
+@register_cli("dev")
+@common_command
+@click.command()
+def dev():
+    """Start development server"""
+    # ...
+```
+
+Common commands appear in a separate "Common Commands" section when running `plain --help`.
+
+## Shell
+
+The `plain shell` command starts an interactive Python shell with your Plain app already loaded.
 
 ```bash
-$ plain example-subgroup-name example-command
-An example command!
+$ plain shell
 ```
 
-Technically you can register a CLI from anywhere, but typically you will do it in either `app/cli.py` or a package's `<pkg>/cli.py`, as those modules will be autoloaded by Plain.
+If you have IPython installed, it will be used automatically. You can also specify an interface explicitly:
+
+```bash
+$ plain shell --interface ipython
+$ plain shell --interface bpython
+$ plain shell --interface python
+```
+
+For one-off commands, use the `-c` flag:
+
+```bash
+$ plain shell -c "from app.users.models import User; print(User.query.count())"
+```
+
+### Run a script with app context
+
+The `plain run` command executes a Python script with your app context already set up:
+
+```bash
+$ plain run scripts/import_data.py
+```
+
+This is useful for one-off scripts that need access to your models and settings.
+
+### SHELL_IMPORT
+
+Customize what gets imported automatically when the shell starts by setting `SHELL_IMPORT` in your settings:
+
+```python
+# app/settings.py
+SHELL_IMPORT = "app.shell"
+```
+
+Then create that module with the objects you want available:
+
+```python
+# app/shell.py
+from app.projects.models import Project
+from app.users.models import User
+
+__all__ = ["Project", "User"]
+```
+
+Now when you run `plain shell`, those objects will be automatically imported and available.
+
+## Built-in commands
+
+Plain includes several built-in commands:
+
+| Command               | Description                              |
+| --------------------- | ---------------------------------------- |
+| `plain shell`         | Interactive Python shell                 |
+| `plain run <script>`  | Execute a Python script with app context |
+| `plain server`        | Production-ready WSGI server             |
+| `plain preflight`     | Validation checks before deployment      |
+| `plain create <name>` | Create a new local package               |
+| `plain settings`      | View current settings                    |
+| `plain urls`          | List all URL patterns                    |
+| `plain docs`          | View package documentation               |
+| `plain build`         | Run build commands                       |
+| `plain install`       | Install package dependencies             |
+| `plain upgrade`       | Upgrade Plain packages                   |
+
+Additional commands are added by installed packages (like `plain models migrate` from plain.models).
+
+## FAQs
+
+#### How do I run commands that don't need the app to be set up?
+
+Use the [`without_runtime_setup`](./runtime.py#without_runtime_setup) decorator for commands that don't need access to settings or app code. This is useful for commands that fork processes (like `server`) where setup should happen in the worker process:
+
+```python
+from plain.cli.runtime import without_runtime_setup
+
+
+@without_runtime_setup
+@click.command()
+def server():
+    """Start the server"""
+    # Setup happens in the worker process, not here
+    # ...
+```
+
+#### Where should I put my custom commands?
+
+Put app-specific commands in `app/cli.py`. Plain will automatically import this module. If you're building a reusable package, put commands in `<package>/cli.py`.
+
+#### Can I use argparse instead of Click?
+
+No, Plain's CLI is built on Click and the registration system expects Click commands. However, Click is well-documented and provides a better developer experience than argparse for most use cases.
+
+## Installation
+
+The CLI is included with Plain. No additional installation is required.

plain/cli/__init__.py

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

plain/cli/agent.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import pkgutil
+import shutil
+from pathlib import Path
+
+import click
+
+
+def _get_packages_with_skills() -> dict[str, list[Path]]:
+    """Get dict mapping package names to lists of skill directory paths.
+
+    Each skill is a directory containing a SKILL.md file.
+    """
+    skills_dirs: dict[str, list[Path]] = {}
+
+    # 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)
+                skills_dir = plain_path / "skills"
+                if skills_dir.exists() and skills_dir.is_dir():
+                    # Find subdirectories that contain SKILL.md
+                    skill_dirs = [
+                        d
+                        for d in skills_dir.iterdir()
+                        if d.is_dir() and (d / "SKILL.md").exists()
+                    ]
+                    if skill_dirs:
+                        skills_dirs["plain"] = skill_dirs
+                    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 skills/ directory at package root
+                            skills_dir = package_path / "skills"
+                            if skills_dir.exists() and skills_dir.is_dir():
+                                # Find subdirectories that contain SKILL.md
+                                skill_dirs = [
+                                    d
+                                    for d in skills_dir.iterdir()
+                                    if d.is_dir() and (d / "SKILL.md").exists()
+                                ]
+                                if skill_dirs:
+                                    skills_dirs[modname] = skill_dirs
+                    except Exception:
+                        continue
+    except Exception:
+        pass
+
+    return skills_dirs
+
+
+def _get_skill_destinations() -> list[Path]:
+    """Get list of skill directories to install to based on what's present."""
+    cwd = Path.cwd()
+    destinations = []
+
+    # Check for Claude (.claude/ directory)
+    if (cwd / ".claude").exists():
+        destinations.append(cwd / ".claude" / "skills")
+
+    # Check for Codex (.codex/ directory)
+    if (cwd / ".codex").exists():
+        destinations.append(cwd / ".codex" / "skills")
+
+    return destinations
+
+
+def _install_skills_to(
+    dest_skills_dir: Path, skills_by_package: dict[str, list[Path]]
+) -> tuple[int, int]:
+    """Install skills to a destination directory. Returns (installed_count, removed_count)."""
+    dest_skills_dir.mkdir(parents=True, exist_ok=True)
+
+    # Collect all source skill names
+    source_skill_names: set[str] = set()
+    for skill_dirs in skills_by_package.values():
+        for skill_dir in skill_dirs:
+            source_skill_names.add(skill_dir.name)
+
+    installed_count = 0
+    removed_count = 0
+
+    # Remove orphaned plain-* skills (exist in dest but not in source)
+    # Only remove skills with plain- prefix to preserve user-created skills
+    if dest_skills_dir.exists():
+        for dest_dir in dest_skills_dir.iterdir():
+            if (
+                dest_dir.is_dir()
+                and dest_dir.name.startswith("plain-")
+                and dest_dir.name not in source_skill_names
+            ):
+                shutil.rmtree(dest_dir)
+                removed_count += 1
+
+    for pkg_name in sorted(skills_by_package.keys()):
+        for skill_dir in skills_by_package[pkg_name]:
+            dest_dir = dest_skills_dir / skill_dir.name
+            source_skill_file = skill_dir / "SKILL.md"
+
+            # Check if we need to copy (mtime checking)
+            if dest_dir.exists():
+                dest_skill_file = dest_dir / "SKILL.md"
+                if dest_skill_file.exists():
+                    source_mtime = source_skill_file.stat().st_mtime
+                    dest_mtime = dest_skill_file.stat().st_mtime
+                    if source_mtime <= dest_mtime:
+                        continue
+
+            # Copy the entire skill directory
+            if dest_dir.exists():
+                shutil.rmtree(dest_dir)
+            shutil.copytree(skill_dir, dest_dir)
+            installed_count += 1
+
+    return installed_count, removed_count
+
+
+def _setup_session_hook(dest_dir: Path) -> None:
+    """Create or update settings.json with SessionStart hook."""
+    settings_file = dest_dir / "settings.json"
+
+    # Load existing settings or start fresh
+    if settings_file.exists():
+        settings = json.loads(settings_file.read_text())
+    else:
+        settings = {}
+
+    # Ensure hooks structure exists
+    if "hooks" not in settings:
+        settings["hooks"] = {}
+
+    # Define the Plain hook - calls the agent context command directly
+    plain_hook = {
+        "matcher": "startup|resume",
+        "hooks": [
+            {
+                "type": "command",
+                "command": "uv run plain agent context 2>/dev/null || true",
+            }
+        ],
+    }
+
+    # Get existing SessionStart hooks, remove any existing plain hook
+    session_hooks = settings["hooks"].get("SessionStart", [])
+    session_hooks = [h for h in session_hooks if "plain agent" not in str(h)]
+    # Also remove old plain-context.md hooks for migration
+    session_hooks = [h for h in session_hooks if "plain-context.md" not in str(h)]
+    session_hooks.append(plain_hook)
+    settings["hooks"]["SessionStart"] = session_hooks
+
+    settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+
+
+@click.group()
+def agent() -> None:
+    """AI agent integration for Plain projects"""
+    pass
+
+
+@agent.command()
+def context() -> None:
+    """Output Plain framework context for AI agents"""
+    click.echo("This is a Plain project. Use the /plain-* skills for common tasks.")
+
+
+@agent.command()
+def install() -> None:
+    """Install skills and hooks to agent directories"""
+    skills_by_package = _get_packages_with_skills()
+
+    if not skills_by_package:
+        click.echo("No skills found in installed packages.")
+        return
+
+    # Find destinations based on what agent directories exist
+    destinations = _get_skill_destinations()
+
+    if not destinations:
+        click.secho(
+            "No agent directories found (.claude/ or .codex/)",
+            fg="yellow",
+        )
+        return
+
+    # Install to each destination
+    for dest in destinations:
+        installed_count, removed_count = _install_skills_to(dest, skills_by_package)
+
+        parent_dir = dest.parent  # .claude/ or .codex/
+
+        # Setup hook only for Claude (Codex uses a different config format)
+        if parent_dir.name == ".claude":
+            _setup_session_hook(parent_dir)
+
+        parts = []
+        if installed_count > 0:
+            parts.append(f"installed {installed_count} skills")
+        if removed_count > 0:
+            parts.append(f"removed {removed_count} skills")
+        if parent_dir.name == ".claude":
+            parts.append("updated hooks")
+        if parts:
+            click.echo(f"Agent: {', '.join(parts)} in {parent_dir}/")
+
+
+@agent.command()
+def skills() -> None:
+    """List available skills from installed packages"""
+    skills_by_package = _get_packages_with_skills()
+
+    if not skills_by_package:
+        click.echo("No skills found in installed packages.")
+        return
+
+    click.echo("Available skills:")
+    for pkg_name in sorted(skills_by_package.keys()):
+        for skill_dir in skills_by_package[pkg_name]:
+            click.echo(f"  - {skill_dir.name} (from {pkg_name})")

plain/cli/build.py

@@ -9,6 +9,7 @@ import click
 
 import plain.runtime
 from plain.assets.compile import compile_assets, get_compiled_path
+from plain.cli.print import print_event
 
 
 @click.command()
@@ -33,8 +34,8 @@ from plain.assets.compile import compile_assets, get_compiled_path
     default=True,
     help="Compress the assets",
 )
-def build(keep_original, fingerprint, compress):
-    """Pre-deployment build step (compile assets, css, js, etc.)"""
+def build(keep_original: bool, fingerprint: bool, compress: bool) -> None:
+    """Pre-deployment build step for assets and static files"""
 
     if not keep_original and not fingerprint:
         raise click.UsageError(
@@ -54,18 +55,16 @@ def build(keep_original, fingerprint, compress):
             .get("run", {})
             .items()
         ):
-            click.secho(f"Running {name} from pyproject.toml", bold=True)
+            print_event(f"{name}...")
             result = subprocess.run(data["cmd"], shell=True)
-            print()
             if result.returncode:
                 click.secho(f"Error in {name} (exit {result.returncode})", fg="red")
                 sys.exit(result.returncode)
 
     # Then run installed package build steps (like tailwind, typically should run last...)
     for entry_point in entry_points(group="plain.build"):
-        click.secho(f"Running {entry_point.name}", bold=True)
-        result = entry_point.load()()
-        print()
+        print_event(f"{entry_point.name}...")
+        entry_point.load()()
 
     # Compile our assets
     target_dir = get_compiled_path()
@@ -79,7 +78,7 @@ def build(keep_original, fingerprint, compress):
     total_compiled = 0
 
     for url_path, resolved_url_path, compiled_paths in compile_assets(
-        target_dir=target_dir,
+        target_dir=str(target_dir),
         keep_original=keep_original,
         fingerprint=fingerprint,
         compress=compress,

plain/cli/changelog.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import re
 from importlib.util import find_spec
 from pathlib import Path
@@ -5,9 +7,10 @@ from pathlib import Path
 import click
 
 from .output import style_markdown
+from .runtime import without_runtime_setup
 
 
-def parse_version(version_str):
+def parse_version(version_str: str) -> tuple[int, ...]:
     """Parse a version string into a tuple of integers for comparison."""
     # Remove 'v' prefix if present and split by dots
     clean_version = version_str.lstrip("v")
@@ -22,7 +25,7 @@ def parse_version(version_str):
     return tuple(parts)
 
 
-def compare_versions(v1, v2):
+def compare_versions(v1: str, v2: str) -> int:
     """Compare two version strings. Returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2."""
     parsed_v1 = parse_version(v1)
     parsed_v2 = parse_version(v2)
@@ -40,12 +43,15 @@ def compare_versions(v1, v2):
         return 0
 
 
+@without_runtime_setup
 @click.command("changelog")
 @click.argument("package_label")
 @click.option("--from", "from_version", help="Show entries from this version onwards")
 @click.option("--to", "to_version", help="Show entries up to this version")
-def changelog(package_label, from_version, to_version):
-    """Show changelog entries for a package."""
+def changelog(
+    package_label: str, from_version: str | None, to_version: str | None
+) -> None:
+    """Show changelog for a package"""
     module_name = package_label.replace("-", ".")
     spec = find_spec(module_name)
     if not spec:
@@ -85,7 +91,7 @@ def changelog(package_label, from_version, to_version):
     if current_version is not None:
         entries.append((current_version, current_lines))
 
-    def version_found(version):
+    def version_found(version: str) -> bool:
         return any(compare_versions(v, version) == 0 for v, _ in entries)
 
     if from_version and not version_found(from_version):