pulse-framework 0.1.0__py3-none-any.whl

pulse/cmd.py

@@ -0,0 +1,324 @@
+"""
+Command-line interface for Pulse UI.
+This module provides the CLI commands for running the server and generating routes.
+"""
+
+import asyncio
+import importlib.util
+import os
+import pty
+import socket
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from pulse.app import App
+# from pulse.routing import clear_routes
+
+from textual.app import App as TextualApp, ComposeResult
+from textual.containers import Container
+from textual.widgets import RichLog
+from rich.text import Text
+
+cli = typer.Typer(
+    name="pulse",
+    help="Pulse UI - Python to TypeScript bridge with server-side callbacks",
+    no_args_is_help=True,
+)
+
+
+def find_available_port(start_port: int = 8000, max_attempts: int = 100) -> int:
+    """Find an available port starting from start_port."""
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("localhost", port))
+                return port
+        except OSError:
+            continue
+    raise RuntimeError(
+        f"Could not find an available port after {max_attempts} attempts starting from {start_port}"
+    )
+
+
+def load_app_from_file(file_path: str | Path) -> App:
+    """Load routes from a Python file (supports both App instances and global @ps.route decorators)."""
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        typer.echo(f"❌ File not found: {file_path}")
+        raise typer.Exit(1)
+
+    if not file_path.suffix == ".py":
+        typer.echo(f"❌ File must be a Python file (.py): {file_path}")
+        raise typer.Exit(1)
+
+    # clear_routes()
+    sys.path.insert(0, str(file_path.parent.absolute()))
+
+    try:
+        spec = importlib.util.spec_from_file_location("user_app", file_path)
+        if spec is None or spec.loader is None:
+            typer.echo(f"❌ Could not load module from: {file_path}")
+            raise typer.Exit(1)
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        if hasattr(module, "app") and isinstance(module.app, App):
+            app_instance = module.app
+            if not app_instance.routes:
+                typer.echo(f"⚠️  No routes found in {file_path}")
+            return app_instance
+
+        typer.echo(f"⚠️  No app found in {file_path}")
+        raise typer.Exit(1)
+
+    except Exception as e:
+        typer.echo(f"❌ Error loading {file_path}: {e}")
+        raise typer.Exit(1)
+    finally:
+        if str(file_path.parent.absolute()) in sys.path:
+            sys.path.remove(str(file_path.parent.absolute()))
+
+
+class Terminal(RichLog):
+    """A widget that runs a command in a pseudo-terminal."""
+
+    def __init__(self, command, cwd, env=None, **kwargs):
+        super().__init__(highlight=True, markup=True, wrap=False, **kwargs)
+        self.command = command
+        self.cwd = cwd
+        self.env = env
+        self.pid = None
+        self.fd = None
+
+    async def on_mount(self) -> None:
+        """Start the command when the widget is mounted."""
+        self.pid, self.fd = pty.fork()
+
+        if self.pid == 0:  # Child process
+            os.chdir(self.cwd)
+            env = os.environ.copy()
+            if self.env:
+                env.update(self.env)
+            os.execvpe(self.command[0], self.command, env)
+        else:  # Parent process
+            loop = asyncio.get_running_loop()
+            loop.add_reader(self.fd, self.read_from_pty)
+
+    def read_from_pty(self) -> None:
+        """Read from the PTY and update the widget."""
+        if self.fd is None:
+            return
+        try:
+            data = os.read(self.fd, 1024)
+            if not data:
+                self.update_log_with_exit_message()
+                return
+            self.write(Text.from_ansi(data.decode(errors="replace")))
+        except OSError:
+            self.update_log_with_exit_message()
+
+    def update_log_with_exit_message(self):
+        if self.fd:
+            asyncio.get_running_loop().remove_reader(self.fd)
+            os.close(self.fd)
+            self.fd = None
+        self.write("\n\n[b red]PROCESS EXITED[/b red]")
+        self.border_style = "red"
+
+    async def on_key(self, event) -> None:
+        if self.fd:
+            if event.key == "ctrl+c":
+                os.write(self.fd, b"\x03")
+            else:
+                os.write(self.fd, event.key.encode())
+
+    def on_unmount(self) -> None:
+        """Ensure the process is terminated on unmount."""
+        if self.pid:
+            try:
+                os.kill(self.pid, 9)
+            except ProcessLookupError:
+                pass
+
+
+class PulseTerminalViewer(TextualApp):
+    """A Textual app to view Pulse server logs in interactive terminals."""
+
+    CSS = """
+    Screen {
+        background: transparent;
+    }
+    #main_container {
+        layout: horizontal;
+        background: transparent;
+    }
+    Terminal {
+        width: 1fr;
+        height: 100%;
+        margin: 0 1;
+        scrollbar-size: 1 1;
+    }
+    Terminal:focus {
+        border: round white;
+    }
+    #server_term {
+        border: round cyan;
+    }
+    #web_term {
+        border: round orange;
+    }
+    """
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def __init__(
+        self,
+        server_command=None,
+        server_cwd=None,
+        server_env=None,
+        web_command=None,
+        web_cwd=None,
+        web_env=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.server_command = server_command
+        self.server_cwd = server_cwd
+        self.server_env = server_env
+        self.web_command = web_command
+        self.web_cwd = web_cwd
+        self.web_env = web_env
+
+    def compose(self) -> ComposeResult:
+        with Container(id="main_container"):
+            if self.server_command:
+                server_term = Terminal(
+                    self.server_command,
+                    self.server_cwd,
+                    self.server_env,
+                    id="server_term",
+                )
+                server_term.border_title = "🐍 Python Server"
+                yield server_term
+
+            if self.web_command:
+                web_term = Terminal(
+                    self.web_command, self.web_cwd, self.web_env, id="web_term"
+                )
+                web_term.border_title = "🌐 Web Server"
+                yield web_term
+
+
+@cli.command("run")
+def run(
+    app_file: str = typer.Argument(..., help="Python file with a pulse.App instance"),
+    address: str = typer.Option("localhost", "--address"),
+    port: int = typer.Option(8000, "--port"),
+    server_only: bool = typer.Option(False, "--server-only"),
+    web_only: bool = typer.Option(False, "--web-only"),
+    no_reload: bool = typer.Option(False, "--no-reload"),
+    find_port: bool = typer.Option(True, "--find-port/--no-find-port"),
+):
+    """Run the Pulse server and web development server together."""
+    if server_only and web_only:
+        typer.echo("❌ Cannot use --server-only and --web-only at the same time.")
+        raise typer.Exit(1)
+
+    if find_port:
+        port = find_available_port(port)
+
+    console = Console()
+    console.log(f"📁 Loading app from: {app_file}")
+    app_instance = load_app_from_file(app_file)
+
+    web_dir = Path(app_instance.codegen.cfg.web_dir)
+    if not web_dir.exists() and not server_only:
+        console.log(f"❌ Directory not found: {web_dir}")
+        raise typer.Exit(1)
+
+    server_command, server_cwd, server_env = None, None, None
+    web_command, web_cwd, web_env = None, None, None
+
+    if not web_only:
+        module_name = Path(app_file).stem
+        app_import_string = f"{module_name}:app.asgi_factory"
+        server_command = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            app_import_string,
+            "--host",
+            address,
+            "--port",
+            str(port),
+            "--factory",
+        ]
+        if not no_reload:
+            server_command.append("--reload")
+
+        server_cwd = Path(app_file).parent
+        server_env = os.environ.copy()
+        server_env.update(
+            {
+                "PULSE_APP_FILE": app_file,
+                "PULSE_HOST": address,
+                "PULSE_PORT": str(port),
+                "PYTHONUNBUFFERED": "1",
+                "FORCE_COLOR": "1",
+            }
+        )
+
+    if not server_only:
+        web_command = ["bun", "run", "dev"]
+        web_cwd = web_dir
+        web_env = os.environ.copy()
+        web_env.update({"FORCE_COLOR": "1"})
+
+    app = PulseTerminalViewer(
+        server_command=server_command,
+        server_cwd=server_cwd,
+        server_env=server_env,
+        web_command=web_command,
+        web_cwd=web_cwd,
+        web_env=web_env,
+    )
+    app.run()
+
+
+@cli.command("generate")
+def generate(
+    app_file: str = typer.Argument(..., help="Path to your Python file with routes"),
+):
+    """Generate TypeScript routes without starting the server."""
+    console = Console()
+    console.log("🔄 Generating TypeScript routes...")
+
+    console.log(f"📁 Loading routes from: {app_file}")
+    app = load_app_from_file(app_file)
+    console.log(f"📋 Found {len(app.routes.flat_tree)} routes")
+
+    app.run_codegen("127.0.0.1:8000")
+
+    if len(app.routes.flat_tree) > 0:
+        console.log(f"✅ Generated {len(app.routes.flat_tree)} routes successfully!")
+    else:
+        console.log("⚠️  No routes found to generate")
+
+
+def main():
+    """Main CLI entry point."""
+    try:
+        cli()
+    except Exception as e:
+        console = Console()
+        console.log(f"❌ Error: {e}")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    main()

pulse/codegen.py

@@ -0,0 +1,147 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.templates import LAYOUT_TEMPLATE, ROUTE_TEMPLATE, ROUTES_CONFIG_TEMPLATE
+
+from .routing import Layout, Route, RouteTree
+
+logger = logging.getLogger(__file__)
+
+
+@dataclass
+class CodegenConfig:
+    """
+    Configuration for code generation.
+
+    Attributes:
+        web_dir (str): Root directory for the web output.
+        pulse_dir (str): Name of the Pulse app directory.
+        lib_path (str): Path to the Pulse library.
+        pulse_path (Path): Full path to the generated app directory.
+    """
+
+    web_dir: Path | str = "pulse-web"
+    """Root directory for the web output."""
+
+    pulse_dir: Path | str = "pulse"
+    """Name of the Pulse app directory."""
+
+    lib_path: Path | str = "pulse-ui-client"
+    """Path to the Pulse library."""
+
+    @property
+    def pulse_path(self) -> Path:
+        """Full path to the generated app directory."""
+        return Path(self.web_dir) / "app" / self.pulse_dir
+
+
+def write_file_if_changed(path: Path, content: str) -> Path:
+    """Write content to file only if it has changed."""
+    if path.exists():
+        try:
+            current_content = path.read_text()
+            if current_content == content:
+                return path  # Skip writing, content is the same
+        except Exception:
+            # If we can't read the file for any reason, just write it
+            pass
+
+    path.parent.mkdir(exist_ok=True, parents=True)
+    path.write_text(content)
+    return path
+
+
+class Codegen:
+    def __init__(self, routes: RouteTree, config: CodegenConfig) -> None:
+        self.cfg = config
+        self.routes = routes
+
+    @property
+    def output_folder(self):
+        return self.cfg.pulse_path
+
+    def generate_all(self, server_address: str):
+        # Keep track of all generated files
+        generated_files = [
+            self.generate_layout_tsx(server_address),
+            self.generate_routes_ts(),
+            *(
+                self.generate_route(route, server_address=server_address)
+                for route in self.routes.flat_tree.values()
+            ),
+        ]
+        generated_files = set(generated_files)
+
+        # Clean up any remaining files that are not part of the generated files
+        for path in self.output_folder.rglob("*"):
+            if path.is_file() and path not in generated_files:
+                try:
+                    path.unlink()
+                    logger.debug(f"Removed stale file: {path}")
+                except Exception as e:
+                    logger.warning(f"Could not remove stale file {path}: {e}")
+
+    def generate_layout_tsx(self, server_address: str):
+        """Generates the content of _layout.tsx"""
+        content = str(
+            LAYOUT_TEMPLATE.render_unicode(
+                server_address=server_address, lib_path=self.cfg.lib_path
+            )
+        )
+        # The underscore avoids an eventual naming conflict with a generated
+        # /layout route.
+        return write_file_if_changed(self.output_folder / "_layout.tsx", content)
+
+    def generate_routes_ts(self):
+        """Generate TypeScript code for the routes configuration."""
+        routes_str = self._render_routes_ts(self.routes.tree, 2)
+        content = str(
+            ROUTES_CONFIG_TEMPLATE.render_unicode(
+                routes_str=routes_str,
+                pulse_dir=self.cfg.pulse_dir,
+            )
+        )
+        return write_file_if_changed(self.output_folder / "routes.ts", content)
+
+    def _render_routes_ts(self, routes: list[Route | Layout], indent_level: int) -> str:
+        lines = []
+        indent_str = "  " * indent_level
+        for route in routes:
+            if isinstance(route, Layout):
+                children_str = ""
+                if route.children:
+                    children_str = f"\n{self._render_routes_ts(route.children, indent_level + 1)}\n{indent_str}"
+                lines.append(
+                    f'{indent_str}layout("{self.cfg.pulse_dir}/layouts/{route.file_path()}", [{children_str}]),'
+                )
+            else:
+                if route.children:
+                    children_str = f"\n{self._render_routes_ts(route.children, indent_level + 1)}\n{indent_str}"
+                    lines.append(
+                        f'{indent_str}route("{route.path}", "{self.cfg.pulse_dir}/routes/{route.file_path()}", [{children_str}]),'
+                    )
+                elif route.is_index:
+                    lines.append(
+                        f'{indent_str}index("{self.cfg.pulse_dir}/routes/{route.file_path()}"),'
+                    )
+                else:
+                    lines.append(
+                        f'{indent_str}route("{route.path}", "{self.cfg.pulse_dir}/routes/{route.file_path()}"),'
+                    )
+        return "\n".join(lines)
+
+    def generate_route(self, route: Route | Layout, server_address: str):
+        if isinstance(route, Layout):
+            output_path = self.output_folder / "layouts" / route.file_path()
+        else:
+            output_path = self.output_folder / "routes" / route.file_path()
+        content = str(
+            ROUTE_TEMPLATE.render_unicode(
+                route=route,
+                components=route.components or [],
+                lib_path=self.cfg.lib_path,
+                server_address=server_address,
+            )
+        )
+        return write_file_if_changed(output_path, content)

pulse/components/__init__.py

@@ -0,0 +1 @@
+from .react_router import Link, Outlet

pulse/components/react_router.py

@@ -0,0 +1,43 @@
+from typing import Literal, Optional, TypedDict, Unpack
+from pulse.html.attributes import HTMLAnchorProps
+from pulse.vdom import Child
+from ..react_component import DEFAULT, react_component
+
+
+class LinkPath(TypedDict):
+    pathname: str
+    search: str
+    hash: str
+
+
+@react_component("Link", "react-router")
+def Link(
+    *children: Child,
+    key: Optional[str] = None,
+    to: str,
+    # Default: render
+    discover: Literal["render", "none"] = DEFAULT,
+    # The React Router default is 'none' to match the behavior of regular links,
+    # but 'intent' is more desirable in general
+    prefetch: Literal["none", "intent", "render", "viewport"] = "intent",
+    # Default: False
+    preventScrollReset: bool = DEFAULT,
+    # Default: 'route'
+    relative: Literal["route", "path"] = DEFAULT,
+    # Default: False
+    reloadDocument: bool = DEFAULT,
+    # Default: False
+    replace: bool = DEFAULT,
+    # Default: undefined
+    state: dict = DEFAULT,
+    # Default: False
+    viewTransition=DEFAULT,
+    **props: Unpack[HTMLAnchorProps],
+): ...
+
+
+@react_component("Outlet", "react-router")
+def Outlet(key: Optional[str] = None): ...
+
+
+__all__ = ["Link", "Outlet"]

pulse/context.py

@@ -0,0 +1,15 @@
+# This is more for documentation than actually importing from here
+from .reactive import REACTIVE_CONTEXT
+from .routing import ROUTE_CONTEXT
+# NOTE: SessionContext objecst set both the SESSION_CONTEXT and REACTIVE_CONTEXT
+from .session import SESSION_CONTEXT
+from .hooks import HOOK_CONTEXT
+from .react_component import COMPONENT_REGISTRY
+
+__all__ = [
+    "REACTIVE_CONTEXT",
+    "ROUTE_CONTEXT",
+    "SESSION_CONTEXT",
+    "HOOK_CONTEXT",
+    "COMPONENT_REGISTRY",
+]