plain.dev 0.32.1__py3-none-any.whl → 0.33.0__py3-none-any.whl

plain/dev/CHANGELOG.md

@@ -1,5 +1,20 @@
 # plain-dev changelog
 
+## [0.33.0](https://github.com/dropseed/plain/releases/plain-dev@0.33.0) (2025-07-18)
+
+### What's changed
+
+- Added automatic background startup of dev services when running `plain dev` commands. Services defined in `pyproject.toml` will now start automatically ([0a5ffc6de5](https://github.com/dropseed/plain/commit/0a5ffc6de5)).
+- Added `plain dev logs` command to view output from recent `plain dev` runs. Supports options like `--follow`, `--pid`, `--path`, and `--services` to manage and view different log outputs ([0a5ffc6de5](https://github.com/dropseed/plain/commit/0a5ffc6de5)).
+- Added `--start` and `--stop` flags to both `plain dev` and `plain dev services` commands for running processes in the background. Use `plain dev --start` to launch the dev server in background mode and `plain dev --stop` to terminate it ([0a5ffc6de5](https://github.com/dropseed/plain/commit/0a5ffc6de5)).
+- Improved process management with better PID tracking and graceful shutdown handling for both dev server and services ([0a5ffc6de5](https://github.com/dropseed/plain/commit/0a5ffc6de5)).
+- Improved CLI error handling by using `click.UsageError` instead of manual error printing and `sys.exit()` ([88f06c5184](https://github.com/dropseed/plain/commit/88f06c5184)).
+- Removed `psycopg[binary]` dependency from plain-dev as database drivers should be installed separately based on project needs ([63224001c9](https://github.com/dropseed/plain/commit/63224001c9)).
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.32.1](https://github.com/dropseed/plain/releases/plain-dev@0.32.1) (2025-06-27)
 
 ### What's changed

plain/dev/README.md

@@ -8,6 +8,7 @@ The `plain.dev` package can be [installed from PyPI](https://pypi.org/project/pl
 
 - [`plain dev`](#plain-dev)
 - [`plain dev services`](#plain-dev-services)
+- [`plain dev logs`](#plain-dev-logs)
 - [`plain pre-commit`](#plain-pre-commit)
 - [`plain contrib`](#plain-contrib)
 - [VS Code debugging](#vscode-debugging)
@@ -44,12 +45,26 @@ Unlike [services](#services), custom processes are _only_ run during `plain dev`
 ```toml
 # pyproject.toml
 [tool.plain.dev.run]
-ngrok = {command = "ngrok http $PORT"}
+    ngrok = {command = "ngrok http $PORT"}
 ```
 
 ## `plain dev services`
 
 Starts your [services](#services) by themselves.
+Logs are stored in `.plain/dev/logs/services/`.
+
+## `plain dev logs`
+
+Show output from recent `plain dev` runs.
+
+Logs are stored in `.plain/dev/logs/run/`.
+
+```bash
+plain dev logs        # print last log
+plain dev logs -f     # follow the latest log
+plain dev logs --pid 1234
+plain dev logs --path
+```
 
 ## `plain pre-commit`
 

plain/dev/cli.py

@@ -1,38 +1,75 @@
-import importlib
-import json
-import multiprocessing
 import os
-import platform
-import signal
-import socket
 import subprocess
 import sys
 import time
-import tomllib
 from importlib.metadata import entry_points
-from importlib.util import find_spec
-from pathlib import Path
 
 import click
-from rich.columns import Columns
-from rich.console import Console
-from rich.text import Text
 
 from plain.cli import register_cli
 from plain.runtime import APP_PATH, PLAIN_TEMP_PATH
 
-from .dev_pid import DevPid
-from .mkcert import MkcertManager
-from .poncho.manager import Manager as PonchoManager
-from .poncho.printer import Printer
-from .services import Services, ServicesPid
-from .utils import has_pyproject_toml
+from .core import ENTRYPOINT_GROUP, DevProcess
+from .services import ServicesProcess
 
-ENTRYPOINT_GROUP = "plain.dev"
+
+class DevGroup(click.Group):
+    """Custom group that ensures *services* are running on CLI startup."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._auto_start_services()
+
+    @staticmethod
+    def _auto_start_services():
+        """Start dev *services* in the background if not already running."""
+
+        if os.environ.get("PLAIN_DEV_SERVICES_AUTO", "true") not in [
+            "1",
+            "true",
+            "yes",
+        ]:
+            return
+
+        # Don't do anything if it looks like a "services" command is being run explicitly
+        if "services" in sys.argv or "--stop" in sys.argv:
+            return
+
+        if not ServicesProcess.get_services(APP_PATH.parent):
+            return
+
+        if ServicesProcess.running_pid():
+            return
+
+        click.secho(
+            "Starting background dev services (terminate with `plain dev --stop`)...",
+            dim=True,
+        )
+
+        subprocess.Popen(
+            [sys.executable, "-m", "plain", "dev", "services", "--start"],
+            start_new_session=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        time.sleep(0.5)  # Give it a moment to start
+
+        # If it's already dead, show the output and quit
+        if not ServicesProcess.running_pid():
+            click.secho(
+                "Failed to start dev services. Here are the logs:",
+                fg="red",
+            )
+            subprocess.run(
+                ["plain", "dev", "logs", "--services"],
+                check=False,
+            )
+            sys.exit(1)
 
 
 @register_cli("dev")
-@click.group(invoke_without_command=True)
+@click.group(cls=DevGroup, invoke_without_command=True)
 @click.pass_context
 @click.option(
     "--port",
@@ -40,8 +77,8 @@ ENTRYPOINT_GROUP = "plain.dev"
     default="",
     type=str,
     help=(
-        "Port to run the web server on. If omitted, tries 8443 and "
-        "picks the next free port"
+        "Port to run the web server on. "
+        "If omitted, tries 8443 and picks the next free port."
     ),
 )
 @click.option(
@@ -58,29 +95,73 @@ ENTRYPOINT_GROUP = "plain.dev"
     type=click.Choice(["debug", "info", "warning", "error", "critical", ""]),
     help="Log level",
 )
-def cli(ctx, port, hostname, log_level):
+@click.option(
+    "--start",
+    is_flag=True,
+    default=False,
+    help="Start in the background",
+)
+@click.option(
+    "--stop",
+    is_flag=True,
+    default=False,
+    help="Stop the background process",
+)
+def cli(ctx, port, hostname, log_level, start, stop):
     """Start local development"""
 
     if ctx.invoked_subcommand:
         return
 
-    if DevPid().exists():
-        click.secho("`plain dev` already running", fg="yellow")
-        sys.exit(1)
+    if start and stop:
+        raise click.UsageError(
+            "You cannot use both --start and --stop at the same time."
+        )
+
+    os.environ["PLAIN_DEV_SERVICES_AUTO"] = "false"
 
-    if not hostname:
-        project_name = os.path.basename(
-            os.getcwd()
-        )  # Use the directory name by default
+    dev = DevProcess()
 
-        if has_pyproject_toml(APP_PATH.parent):
-            with open(Path(APP_PATH.parent, "pyproject.toml"), "rb") as f:
-                pyproject = tomllib.load(f)
-                project_name = pyproject.get("project", {}).get("name", project_name)
+    if stop:
+        if ServicesProcess.running_pid():
+            ServicesProcess().stop_process()
+            click.secho("Services stopped.", fg="green")
 
-        hostname = f"{project_name}.localhost"
+        if not dev.running_pid():
+            click.secho("No development server running.", fg="yellow")
+            return
+
+        dev.stop_process()
+        click.secho("Development server stopped.", fg="green")
+        return
 
-    returncode = Dev(port=port, hostname=hostname, log_level=log_level).run()
+    if running_pid := dev.running_pid():
+        click.secho(f"`plain dev` already running (pid={running_pid})", fg="yellow")
+        sys.exit(1)
+
+    if start:
+        args = [sys.executable, "-m", "plain", "dev"]
+        if port:
+            args.extend(["--port", port])
+        if hostname:
+            args.extend(["--hostname", hostname])
+        if log_level:
+            args.extend(["--log-level", log_level])
+
+        result = subprocess.Popen(
+            args=args,
+            start_new_session=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        click.secho(
+            f"Development server started in the background (pid={result.pid}).",
+            fg="green",
+        )
+        return
+
+    dev.setup(port=port, hostname=hostname, log_level=log_level)
+    returncode = dev.run()
     if returncode:
         sys.exit(returncode)
 
@@ -112,13 +193,77 @@ def debug():
 
 
 @cli.command()
-def services():
+@click.option("--start", is_flag=True, help="Start in the background")
+@click.option("--stop", is_flag=True, help="Stop the background process")
+def services(start, stop):
     """Start additional services defined in pyproject.toml"""
-    _services = Services()
-    if _services.are_running():
-        click.secho("Services already running", fg="yellow")
+
+    if start and stop:
+        raise click.UsageError(
+            "You cannot use both --start and --stop at the same time."
+        )
+
+    if stop:
+        if not ServicesProcess.running_pid():
+            click.secho("No services running.", fg="yellow")
+            return
+        ServicesProcess().stop_process()
+        click.secho("Services stopped.", fg="green")
         return
-    _services.run()
+
+    if running_pid := ServicesProcess.running_pid():
+        click.secho(f"Services already running (pid={running_pid})", fg="yellow")
+        sys.exit(1)
+
+    if start:
+        result = subprocess.Popen(
+            args=[sys.executable, "-m", "plain", "dev", "services"],
+            start_new_session=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        click.secho(
+            f"Services started in the background (pid={result.pid}).", fg="green"
+        )
+        return
+
+    ServicesProcess().run()
+
+
+@cli.command()
+@click.option("--follow", "-f", is_flag=True, help="Follow log output")
+@click.option("--pid", type=int, help="PID to show logs for")
+@click.option("--path", is_flag=True, help="Output log file path")
+@click.option("--services", is_flag=True, help="Show logs for services")
+def logs(follow, pid, path, services):
+    """Show logs from recent plain dev runs."""
+
+    if services:
+        log_dir = PLAIN_TEMP_PATH / "dev" / "logs" / "services"
+    else:
+        log_dir = PLAIN_TEMP_PATH / "dev" / "logs" / "run"
+
+    if pid:
+        log_path = log_dir / f"{pid}.log"
+        if not log_path.exists():
+            click.secho(f"No log found for pid {pid}", fg="red")
+            return
+    else:
+        logs = sorted(log_dir.glob("*.log"), key=lambda p: p.stat().st_mtime)
+        if not logs:
+            click.secho("No logs found", fg="yellow")
+            return
+        log_path = logs[-1]
+
+    if path:
+        click.echo(str(log_path))
+        return
+
+    if follow:
+        subprocess.run(["tail", "-f", str(log_path)])
+    else:
+        with log_path.open() as f:
+            click.echo(f.read())
 
 
 @cli.command()
@@ -129,365 +274,10 @@ def services():
 def entrypoint(show_list, entrypoint):
     """Entrypoints registered under plain.dev"""
     if not show_list and not entrypoint:
-        click.secho("Please provide an entrypoint name or use --list", fg="red")
-        sys.exit(1)
+        raise click.UsageError("Please provide an entrypoint name or use --list")
 
     for entry_point in entry_points().select(group=ENTRYPOINT_GROUP):
         if show_list:
             click.echo(entry_point.name)
         elif entrypoint == entry_point.name:
             entry_point.load()()
-
-
-class Dev:
-    def __init__(self, *, port, hostname, log_level):
-        self.hostname = hostname
-        self.log_level = log_level
-
-        self.pid = DevPid()
-
-        if port:
-            self.port = int(port)
-            if not self._port_available(self.port):
-                click.secho(f"Port {self.port} in use", fg="red")
-                raise SystemExit(1)
-        else:
-            self.port = self._find_open_port(8443)
-            if self.port != 8443:
-                click.secho(f"Port 8443 in use, using {self.port}", fg="yellow")
-
-        self.ssl_key_path = None
-        self.ssl_cert_path = None
-
-        self.url = f"https://{self.hostname}:{self.port}"
-        self.tunnel_url = os.environ.get("PLAIN_DEV_TUNNEL_URL", "")
-
-        self.plain_env = {
-            "PYTHONUNBUFFERED": "true",
-            "PLAIN_DEV": "true",
-            **os.environ,
-        }
-
-        if log_level:
-            self.plain_env["PLAIN_LOG_LEVEL"] = log_level.upper()
-            self.plain_env["APP_LOG_LEVEL"] = log_level.upper()
-
-        self.custom_process_env = {
-            **self.plain_env,
-            "PORT": str(self.port),
-            "PLAIN_DEV_URL": self.url,
-        }
-
-        if self.tunnel_url:
-            status_bar = Columns(
-                [
-                    Text.from_markup(
-                        f"[bold]Tunnel[/bold] [underline][link={self.tunnel_url}]{self.tunnel_url}[/link][/underline]"
-                    ),
-                    Text.from_markup(
-                        f"[dim][bold]Server[/bold] [link={self.url}]{self.url}[/link][/dim]"
-                    ),
-                    Text.from_markup(
-                        "[dim][bold]Ctrl+C[/bold] to stop[/dim]",
-                        justify="right",
-                    ),
-                ],
-                expand=True,
-            )
-        else:
-            status_bar = Columns(
-                [
-                    Text.from_markup(
-                        f"[bold]Server[/bold] [underline][link={self.url}]{self.url}[/link][/underline]"
-                    ),
-                    Text.from_markup(
-                        "[dim][bold]Ctrl+C[/bold] to stop[/dim]", justify="right"
-                    ),
-                ],
-                expand=True,
-            )
-        self.console = Console(markup=False, highlight=False)
-        self.console_status = self.console.status(status_bar)
-
-        self.poncho = PonchoManager(printer=Printer(lambda s: self.console.out(s)))
-
-    def _find_open_port(self, start_port):
-        port = start_port
-        while not self._port_available(port):
-            port += 1
-        return port
-
-    def _port_available(self, port):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
-            sock.settimeout(0.5)
-            result = sock.connect_ex(("127.0.0.1", port))
-        return result != 0
-
-    def run(self):
-        self.pid.write()
-        mkcert_manager = MkcertManager()
-        mkcert_manager.setup_mkcert(install_path=Path.home() / ".plain" / "dev")
-        self.ssl_cert_path, self.ssl_key_path = mkcert_manager.generate_certs(
-            domain=self.hostname,
-            storage_path=Path(PLAIN_TEMP_PATH) / "dev" / "certs",
-        )
-
-        self.symlink_plain_src()
-        self.modify_hosts_file()
-        self.set_allowed_hosts()
-        self.run_preflight()
-
-        # If we start services ourselves, we should manage the pidfile
-        services_pid = None
-
-        # Services start first (or are already running from a separate command)
-        if Services.are_running():
-            click.secho("Services already running", fg="yellow")
-        elif services := Services.get_services(APP_PATH.parent):
-            click.secho("\nStarting services...", italic=True, dim=True)
-            services_pid = ServicesPid()
-            services_pid.write()
-
-            for name, data in services.items():
-                env = {
-                    **os.environ,
-                    "PYTHONUNBUFFERED": "true",
-                    **data.get("env", {}),
-                }
-                self.poncho.add_process(name, data["cmd"], env=env)
-
-        # If plain.models is installed (common) then we
-        # will do a couple extra things before starting all of the app-related
-        # processes (this way they don't all have to db-wait or anything)
-        process = None
-        if find_spec("plain.models") is not None:
-            # Use a custom signal to tell the main thread to add
-            # the app processes once the db is ready
-            signal.signal(signal.SIGUSR1, self.start_app)
-
-            process = multiprocessing.Process(
-                target=_process_task, args=(self.plain_env,)
-            )
-            process.start()
-
-            # If there are no poncho processes, then let this process finish before
-            # continuing (vs running in parallel)
-            if self.poncho.num_processes() == 0:
-                # Wait for the process to finish
-                process.join()
-        else:
-            # Start the app processes immediately
-            self.start_app(None, None)
-
-        try:
-            # Start processes we know about and block the main thread
-            self.poncho.loop()
-
-            # Remove the status bar
-            self.console_status.stop()
-        finally:
-            self.pid.rm()
-            # Make sure the services pid gets removed if we set it
-            if services_pid:
-                services_pid.rm()
-
-            # Make sure the process is terminated if it is still running
-            if process and process.is_alive():
-                os.killpg(os.getpgid(process.pid), signal.SIGTERM)
-                process.join(timeout=3)
-                if process.is_alive():
-                    os.killpg(os.getpgid(process.pid), signal.SIGKILL)
-                    process.join()
-
-        return self.poncho.returncode
-
-    def start_app(self, signum, frame):
-        # This runs in the main thread when SIGUSR1 is received
-        # (or called directly if no thread).
-        click.secho("\nStarting app...", italic=True, dim=True)
-
-        # Manually start the status bar now so it isn't bungled by
-        # another thread checking db stuff...
-        self.console_status.start()
-
-        self.add_gunicorn()
-        self.add_entrypoints()
-        self.add_pyproject_run()
-
-    def symlink_plain_src(self):
-        """Symlink the plain package into .plain so we can look at it easily"""
-        plain_path = Path(
-            importlib.util.find_spec("plain.runtime").origin
-        ).parent.parent
-        if not PLAIN_TEMP_PATH.exists():
-            PLAIN_TEMP_PATH.mkdir()
-
-        symlink_path = PLAIN_TEMP_PATH / "src"
-
-        # The symlink is broken
-        if symlink_path.is_symlink() and not symlink_path.exists():
-            symlink_path.unlink()
-
-        # The symlink exists but points to the wrong place
-        if (
-            symlink_path.is_symlink()
-            and symlink_path.exists()
-            and symlink_path.resolve() != plain_path
-        ):
-            symlink_path.unlink()
-
-        if plain_path.exists() and not symlink_path.exists():
-            symlink_path.symlink_to(plain_path)
-
-    def modify_hosts_file(self):
-        """Modify the hosts file to map the custom domain to 127.0.0.1."""
-        entry_identifier = "# Added by plain"
-        hosts_entry = f"127.0.0.1 {self.hostname}  {entry_identifier}"
-
-        if platform.system() == "Windows":
-            hosts_path = Path(r"C:\Windows\System32\drivers\etc\hosts")
-            try:
-                with hosts_path.open("r") as f:
-                    content = f.read()
-
-                if hosts_entry in content:
-                    return  # Entry already exists; no action needed
-
-                # Entry does not exist; add it
-                with hosts_path.open("a") as f:
-                    f.write(f"{hosts_entry}\n")
-                click.secho(f"Added {self.hostname} to {hosts_path}", bold=True)
-            except PermissionError:
-                click.secho(
-                    "Permission denied while modifying hosts file. Please run the script as an administrator.",
-                    fg="red",
-                )
-                sys.exit(1)
-        else:
-            # For macOS and Linux
-            hosts_path = Path("/etc/hosts")
-            try:
-                with hosts_path.open("r") as f:
-                    content = f.read()
-
-                if hosts_entry in content:
-                    return  # Entry already exists; no action needed
-
-                # Entry does not exist; append it using sudo
-                click.secho(
-                    f"Adding {self.hostname} to /etc/hosts file. You may be prompted for your password.\n",
-                    bold=True,
-                )
-                cmd = f"echo '{hosts_entry}' | sudo tee -a {hosts_path} >/dev/null"
-                subprocess.run(cmd, shell=True, check=True)
-                click.secho(f"Added {self.hostname} to {hosts_path}\n", bold=True)
-            except PermissionError:
-                click.secho(
-                    "Permission denied while accessing hosts file.",
-                    fg="red",
-                )
-                sys.exit(1)
-            except subprocess.CalledProcessError:
-                click.secho(
-                    "Failed to modify hosts file. Please ensure you have sudo privileges.",
-                    fg="red",
-                )
-                sys.exit(1)
-
-    def set_allowed_hosts(self):
-        if "PLAIN_ALLOWED_HOSTS" not in os.environ:
-            hostnames = [self.hostname]
-            if self.tunnel_url:
-                # Add the tunnel URL to the allowed hosts
-                hostnames.append(self.tunnel_url.split("://")[1])
-            allowed_hosts = json.dumps(hostnames)
-            self.plain_env["PLAIN_ALLOWED_HOSTS"] = allowed_hosts
-            self.custom_process_env["PLAIN_ALLOWED_HOSTS"] = allowed_hosts
-            click.secho(
-                f"Automatically set PLAIN_ALLOWED_HOSTS={allowed_hosts}", dim=True
-            )
-
-    def run_preflight(self):
-        click.echo()
-        if subprocess.run(["plain", "preflight"], env=self.plain_env).returncode:
-            click.secho("Preflight check failed!", fg="red")
-            sys.exit(1)
-
-    def add_gunicorn(self):
-        # Watch .env files for reload
-        extra_watch_files = []
-        for f in os.listdir(APP_PATH.parent):
-            if f.startswith(".env"):
-                # Needs to be absolute or "./" for inotify to work on Linux...
-                # https://github.com/dropseed/plain/issues/26
-                extra_watch_files.append(str(Path(APP_PATH.parent) / f))
-
-        reload_extra = " ".join(f"--reload-extra-file {f}" for f in extra_watch_files)
-        gunicorn_cmd = [
-            "gunicorn",
-            "--bind",
-            f"{self.hostname}:{self.port}",
-            "--certfile",
-            str(self.ssl_cert_path),
-            "--keyfile",
-            str(self.ssl_key_path),
-            "--threads",
-            "4",
-            "--reload",
-            "plain.wsgi:app",
-            "--timeout",
-            "60",
-            "--log-level",
-            self.log_level or "info",
-            "--access-logfile",
-            "-",
-            "--error-logfile",
-            "-",
-            *reload_extra.split(),
-            "--access-logformat",
-            "'\"%(r)s\" status=%(s)s length=%(b)s time=%(M)sms'",
-            "--log-config-json",
-            str(Path(__file__).parent / "gunicorn_logging.json"),
-        ]
-        gunicorn = " ".join(gunicorn_cmd)
-
-        self.poncho.add_process("plain", gunicorn, env=self.plain_env)
-
-    def add_entrypoints(self):
-        for entry_point in entry_points().select(group=ENTRYPOINT_GROUP):
-            self.poncho.add_process(
-                entry_point.name,
-                f"plain dev entrypoint {entry_point.name}",
-                env=self.plain_env,
-            )
-
-    def add_pyproject_run(self):
-        """Additional processes that only run during `plain dev`."""
-        if not has_pyproject_toml(APP_PATH.parent):
-            return
-
-        with open(Path(APP_PATH.parent, "pyproject.toml"), "rb") as f:
-            pyproject = tomllib.load(f)
-
-        run_commands = (
-            pyproject.get("tool", {}).get("plain", {}).get("dev", {}).get("run", {})
-        )
-        for name, data in run_commands.items():
-            env = {
-                **self.custom_process_env,
-                **data.get("env", {}),
-            }
-            self.poncho.add_process(name, data["cmd"], env=env)
-
-
-def _process_task(env):
-    # Make this process the leader of a new group which can be killed together if it doesn't finish
-    os.setsid()
-
-    subprocess.run(["plain", "models", "db-wait"], env=env, check=True)
-    subprocess.run(["plain", "migrate", "--backup"], env=env, check=True)
-
-    # preflight with db?
-
-    # Send SIGUSR1 to the parent process so the parent's handler is invoked
-    os.kill(os.getppid(), signal.SIGUSR1)