procler 0.2.0__py3-none-any.whl

procler/__init__.py

@@ -0,0 +1,3 @@
+"""Procler - LLM-first process manager for developers."""
+
+__version__ = "0.1.0"

procler/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m procler."""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

procler/api/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI application for Procler."""
+
+from .app import app, create_app
+
+__all__ = ["app", "create_app"]

procler/api/app.py

@@ -0,0 +1,261 @@
+"""FastAPI application factory."""
+
+import asyncio
+import os
+import signal
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from .. import __version__
+from ..logging import logger
+
+# Static files directory (where Vue build output goes)
+STATIC_DIR = Path(__file__).parent.parent / "static"
+
+# Background task for log rotation
+_log_rotation_task: asyncio.Task | None = None
+_shutdown_event = asyncio.Event()
+
+
+async def _log_rotation_loop():
+    """Background task to rotate logs periodically."""
+    from ..core import get_process_manager
+
+    rotation_interval = int(os.environ.get("PROCLER_LOG_ROTATION_INTERVAL", 3600))  # 1 hour default
+    max_logs = int(os.environ.get("PROCLER_MAX_LOGS_PER_PROCESS", 10000))
+
+    logger.info(f"Log rotation started (interval={rotation_interval}s, max_logs={max_logs})")
+
+    while not _shutdown_event.is_set():
+        try:
+            await asyncio.sleep(rotation_interval)
+            if _shutdown_event.is_set():
+                break
+
+            manager = get_process_manager()
+            rotated = await asyncio.to_thread(manager.cleanup_all_logs, max_logs)
+            if rotated:
+                logger.info(f"Rotated logs for {len(rotated)} processes")
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            logger.error(f"Log rotation error: {e}")
+
+
+async def _recover_processes():
+    """Check for orphaned processes on startup and update their status."""
+
+    from ..db import init_database
+    from ..models import Process, ProcessStatus
+
+    init_database()
+
+    # Find processes marked as running
+    all_procs = Process.query().all()
+    running = [p for p in all_procs if p.status in [ProcessStatus.RUNNING.value, ProcessStatus.STARTING.value]]
+
+    if not running:
+        return
+
+    logger.info(f"Checking {len(running)} processes marked as running...")
+
+    for proc in running:
+        if proc.pid:
+            # Check if PID is still running
+            try:
+                os.kill(proc.pid, 0)  # Signal 0 = check if process exists
+                logger.debug(f"Process '{proc.name}' (PID {proc.pid}) is still running")
+            except (OSError, ProcessLookupError):
+                # Process is dead, update status
+                logger.warning(f"Process '{proc.name}' (PID {proc.pid}) is dead, marking as stopped")
+                proc.status = ProcessStatus.STOPPED.value
+                proc.pid = None
+                proc.save()
+        else:
+            # No PID but marked as running - mark as stopped
+            logger.warning(f"Process '{proc.name}' has no PID but marked running, fixing")
+            proc.status = ProcessStatus.STOPPED.value
+            proc.save()
+
+
+async def _graceful_shutdown():
+    """Stop all running processes gracefully."""
+    from ..core import get_process_manager
+
+    # Check if already shutting down to prevent loops
+    if _shutdown_event.is_set():
+        return
+
+    logger.info("Graceful shutdown initiated...")
+    _shutdown_event.set()
+
+    manager = get_process_manager()
+    result = await manager.status()
+
+    if result["success"]:
+        running = [p for p in result["data"]["processes"] if p["status"] == "running"]
+        if running:
+            logger.info(f"Stopping {len(running)} running processes...")
+            for proc in running:
+                try:
+                    await manager.stop(proc["name"], timeout=5.0)
+                    logger.debug(f"Stopped '{proc['name']}'")
+                except Exception as e:
+                    logger.error(f"Failed to stop '{proc['name']}': {e}")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan handler for startup and shutdown."""
+    global _log_rotation_task
+
+    # Startup
+    logger.info(f"Procler v{__version__} starting...")
+
+    # Recover orphaned processes
+    await _recover_processes()
+
+    # Start log rotation background task
+    _log_rotation_task = asyncio.create_task(_log_rotation_loop())
+
+    # Register signal handlers for graceful shutdown
+    # Only trigger shutdown once even if signal received multiple times
+    shutdown_triggered = False
+
+    def handle_shutdown_signal():
+        nonlocal shutdown_triggered
+        if not shutdown_triggered:
+            shutdown_triggered = True
+            _shutdown_event.set()
+
+    loop = asyncio.get_event_loop()
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            loop.add_signal_handler(sig, handle_shutdown_signal)
+        except NotImplementedError:
+            # Windows doesn't support add_signal_handler
+            pass
+
+    logger.info("Procler ready")
+
+    yield
+
+    # Shutdown
+    logger.info("Procler shutting down...")
+
+    # Cancel log rotation task
+    if _log_rotation_task:
+        _log_rotation_task.cancel()
+        try:
+            await _log_rotation_task
+        except asyncio.CancelledError:
+            pass
+
+    # Graceful shutdown of processes
+    await _graceful_shutdown()
+
+    logger.info("Procler stopped")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Procler",
+        description="LLM-first process manager for developers",
+        version=__version__,
+        docs_url="/api/docs",
+        redoc_url="/api/redoc",
+        openapi_url="/api/openapi.json",
+        lifespan=lifespan,
+    )
+
+    # Global exception handler for unexpected errors
+    @app.exception_handler(Exception)
+    async def global_exception_handler(request: Request, exc: Exception):
+        """Handle unexpected exceptions with structured JSON response."""
+        # Log the error for debugging
+        logger.exception(f"Unexpected error handling {request.method} {request.url.path}")
+
+        return JSONResponse(
+            status_code=500,
+            content={
+                "success": False,
+                "error": "Internal server error",
+                "error_code": "internal_error",
+                "detail": str(exc) if os.environ.get("PROCLER_DEBUG") else None,
+            },
+        )
+
+    # Configure CORS
+    # In development, Vite runs on :5173 and proxies /api to backend
+    # In production, everything is served from the same origin
+    cors_origins = os.environ.get("PROCLER_CORS_ORIGINS", "").split(",")
+    cors_origins = [o.strip() for o in cors_origins if o.strip()]
+
+    # Default development origins
+    if not cors_origins:
+        cors_origins = [
+            "http://localhost:5173",  # Vite dev server
+            "http://127.0.0.1:5173",
+            "http://localhost:8000",  # Same origin
+            "http://127.0.0.1:8000",
+        ]
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Include API routers
+    from .routes import config, groups, logs, processes, recipes, snippets, ws
+
+    app.include_router(processes.router, prefix="/api/processes", tags=["processes"])
+    app.include_router(groups.router, prefix="/api/groups", tags=["groups"])
+    app.include_router(recipes.router, prefix="/api/recipes", tags=["recipes"])
+    app.include_router(config.router, prefix="/api/config", tags=["config"])
+    app.include_router(logs.router, prefix="/api/logs", tags=["logs"])
+    app.include_router(snippets.router, prefix="/api/snippets", tags=["snippets"])
+    app.include_router(ws.router, prefix="/api", tags=["websocket"])
+
+    @app.get("/api/health")
+    async def health_check():
+        """Health check endpoint."""
+        return {"status": "healthy", "version": __version__}
+
+    # Serve static files if they exist (production mode)
+    if STATIC_DIR.exists() and (STATIC_DIR / "index.html").exists():
+        # Mount static assets (js, css, etc.)
+        app.mount("/assets", StaticFiles(directory=STATIC_DIR / "assets"), name="assets")
+
+        # Serve index.html for SPA routing (catch-all for non-API routes)
+        @app.get("/{full_path:path}")
+        async def serve_spa(request: Request, full_path: str):
+            """Serve the SPA for all non-API routes."""
+            # Don't serve index.html for API routes
+            if full_path.startswith("api/"):
+                return JSONResponse(
+                    {"success": False, "error": "Not found", "error_code": "not_found"},
+                    status_code=404,
+                )
+
+            # Check if it's a static file request
+            static_file = STATIC_DIR / full_path
+            if static_file.exists() and static_file.is_file():
+                return FileResponse(static_file)
+
+            # Return index.html for SPA routing
+            return FileResponse(STATIC_DIR / "index.html")
+
+    return app
+
+
+# Create default app instance
+app = create_app()

procler/api/deps.py

@@ -0,0 +1,21 @@
+"""Dependency injection for FastAPI routes."""
+
+from ..core import ProcessManager, SnippetManager, get_process_manager, get_snippet_manager
+from ..db import init_database
+
+
+def get_db():
+    """Initialize and return the database."""
+    return init_database()
+
+
+def get_manager() -> ProcessManager:
+    """Get the ProcessManager instance."""
+    init_database()
+    return get_process_manager()
+
+
+def get_snippets() -> SnippetManager:
+    """Get the SnippetManager instance."""
+    init_database()
+    return get_snippet_manager()

procler/api/routes/__init__.py

@@ -0,0 +1,5 @@
+"""API route modules."""
+
+from . import config, groups, logs, processes, recipes, snippets, ws
+
+__all__ = ["config", "groups", "logs", "processes", "recipes", "snippets", "ws"]

procler/api/routes/config.py

@@ -0,0 +1,290 @@
+"""Config management API routes."""
+
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ...config import (
+    find_config_dir,
+    get_changelog_path,
+    get_config,
+    get_config_file_path,
+    read_changelog,
+    reload_config,
+)
+
+router = APIRouter()
+
+
+class ConfigResponse(BaseModel):
+    """Standard response wrapper."""
+
+    success: bool
+    data: dict[str, Any] | None = None
+    error: str | None = None
+    error_code: str | None = None
+
+
+@router.get("")
+async def get_config_info() -> ConfigResponse:
+    """Get current config status and overview."""
+    try:
+        config = get_config()
+        config_path = get_config_file_path()
+        changelog_path = get_changelog_path()
+        config_dir = find_config_dir()
+
+        return ConfigResponse(
+            success=True,
+            data={
+                "config_dir": str(config_dir),
+                "config_file": str(config_path),
+                "config_exists": config_path.exists(),
+                "changelog_file": str(changelog_path),
+                "changelog_exists": changelog_path.exists(),
+                "version": config.version,
+                "vars": config.vars,
+                "stats": {
+                    "processes": len(config.processes),
+                    "groups": len(config.groups),
+                    "recipes": len(config.recipes),
+                    "snippets": len(config.snippets),
+                    "vars": len(config.vars),
+                },
+            },
+        )
+    except Exception as e:
+        return ConfigResponse(
+            success=False,
+            error=str(e),
+            error_code="config_error",
+        )
+
+
+@router.get("/processes")
+async def list_config_processes() -> ConfigResponse:
+    """List all processes defined in config (not runtime DB)."""
+    config = get_config()
+
+    processes = []
+    for name, proc in config.processes.items():
+        processes.append(
+            {
+                "name": name,
+                "command": proc.command,
+                "context": proc.context.value,
+                "container": proc.container,
+                "cwd": proc.cwd,
+                "description": proc.description,
+                "tags": proc.tags,
+            }
+        )
+
+    return ConfigResponse(
+        success=True,
+        data={
+            "processes": processes,
+            "count": len(processes),
+        },
+    )
+
+
+@router.post("/reload")
+async def reload_config_endpoint() -> ConfigResponse:
+    """Reload config from disk."""
+    try:
+        config = reload_config()
+        return ConfigResponse(
+            success=True,
+            data={
+                "reloaded": True,
+                "version": config.version,
+                "stats": {
+                    "processes": len(config.processes),
+                    "groups": len(config.groups),
+                    "recipes": len(config.recipes),
+                    "snippets": len(config.snippets),
+                },
+            },
+        )
+    except Exception as e:
+        return ConfigResponse(
+            success=False,
+            error=str(e),
+            error_code="reload_error",
+        )
+
+
+@router.get("/changelog")
+async def get_changelog(tail: int = 50, format: str = "parsed") -> ConfigResponse:
+    """
+    Get recent changelog entries.
+
+    Args:
+        tail: Number of entries to return (default 50)
+        format: "parsed" for structured JSON entries, "raw" for text lines
+    """
+    changelog_path = get_changelog_path()
+
+    if not changelog_path.exists():
+        return ConfigResponse(
+            success=True,
+            data={
+                "entries": [],
+                "count": 0,
+                "format": format,
+            },
+        )
+
+    try:
+        if format == "parsed":
+            # Return structured JSON entries - LLM-friendly
+            all_entries = read_changelog()
+            entries = all_entries[-tail:] if len(all_entries) > tail else all_entries
+            return ConfigResponse(
+                success=True,
+                data={
+                    "entries": entries,
+                    "count": len(entries),
+                    "total": len(all_entries),
+                    "format": "parsed",
+                },
+            )
+        else:
+            # Return raw lines
+            lines = changelog_path.read_text().strip().splitlines()
+            recent_lines = lines[-tail:] if len(lines) > tail else lines
+            entries = [line for line in recent_lines if line.strip()]
+            return ConfigResponse(
+                success=True,
+                data={
+                    "entries": entries,
+                    "count": len(entries),
+                    "total": len(lines),
+                    "format": "raw",
+                },
+            )
+    except Exception as e:
+        return ConfigResponse(
+            success=False,
+            error=str(e),
+            error_code="changelog_error",
+        )
+
+
+@router.get("/explain")
+async def explain_config() -> ConfigResponse:
+    """
+    Get a plain-language explanation of what the current config defines.
+
+    This is designed for LLM consumption - it describes what the config
+    will do in natural language.
+    """
+    config = get_config()
+    config_path = get_config_file_path()
+
+    if not config_path.exists():
+        return ConfigResponse(
+            success=True,
+            data={
+                "summary": "No config file found. Run 'procler config init' to create one.",
+                "sections": [],
+            },
+        )
+
+    sections = []
+
+    # Explain processes
+    if config.processes:
+        proc_explanations = []
+        for name, proc in config.processes.items():
+            ctx = "locally" if proc.context.value == "local" else f"in Docker container '{proc.container}'"
+            desc = f"'{name}': runs `{proc.command}` {ctx}"
+            if proc.cwd:
+                desc += f" (working dir: {proc.cwd})"
+            if proc.description:
+                desc += f" - {proc.description}"
+            proc_explanations.append(desc)
+        sections.append(
+            {
+                "type": "processes",
+                "title": f"{len(config.processes)} Process Definitions",
+                "explanation": "These processes can be started, stopped, and monitored individually.",
+                "items": proc_explanations,
+            }
+        )
+
+    # Explain groups
+    if config.groups:
+        group_explanations = []
+        for name, group in config.groups.items():
+            stop_order = group.get_stop_order()
+            is_reversed = stop_order == list(reversed(group.processes))
+            stop_desc = "reversed order" if is_reversed else f"custom order: {' → '.join(stop_order)}"
+            desc = f"'{name}': starts [{' → '.join(group.processes)}], stops in {stop_desc}"
+            if group.description:
+                desc += f" - {group.description}"
+            group_explanations.append(desc)
+        sections.append(
+            {
+                "type": "groups",
+                "title": f"{len(config.groups)} Process Groups",
+                "explanation": "Groups start processes in order and stop them in reverse (or custom) order.",
+                "items": group_explanations,
+            }
+        )
+
+    # Explain recipes
+    if config.recipes:
+        recipe_explanations = []
+        for name, recipe in config.recipes.items():
+            steps = recipe.get_steps()
+            step_summary = f"{len(steps)} steps"
+            error_handling = "stops on error" if recipe.on_error.value == "stop" else "continues on error"
+            desc = f"'{name}': {step_summary}, {error_handling}"
+            if recipe.description:
+                desc += f" - {recipe.description}"
+            recipe_explanations.append(desc)
+        sections.append(
+            {
+                "type": "recipes",
+                "title": f"{len(config.recipes)} Recipes",
+                "explanation": "Recipes are multi-step operations that automate common workflows.",
+                "items": recipe_explanations,
+            }
+        )
+
+    # Explain snippets
+    if config.snippets:
+        snippet_explanations = []
+        for name, snippet in config.snippets.items():
+            ctx = "locally" if snippet.context.value == "local" else f"in Docker '{snippet.container}'"
+            desc = f"'{name}': `{snippet.command}` ({ctx})"
+            if snippet.description:
+                desc += f" - {snippet.description}"
+            snippet_explanations.append(desc)
+        sections.append(
+            {
+                "type": "snippets",
+                "title": f"{len(config.snippets)} Snippets",
+                "explanation": "Snippets are reusable commands you can run quickly.",
+                "items": snippet_explanations,
+            }
+        )
+
+    # Build summary
+    total = len(config.processes) + len(config.groups) + len(config.recipes) + len(config.snippets)
+    summary = (
+        f"Config defines {total} items: {len(config.processes)} processes, "
+        f"{len(config.groups)} groups, {len(config.recipes)} recipes, {len(config.snippets)} snippets."
+    )
+
+    return ConfigResponse(
+        success=True,
+        data={
+            "summary": summary,
+            "sections": sections,
+            "config_file": str(config_path),
+        },
+    )

procler/api/routes/groups.py

@@ -0,0 +1,62 @@
+"""Group management API routes."""
+
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ...core.groups import get_group_manager
+
+router = APIRouter()
+
+
+class GroupResponse(BaseModel):
+    """Standard response wrapper."""
+
+    success: bool
+    data: dict[str, Any] | None = None
+    error: str | None = None
+    error_code: str | None = None
+    suggestion: str | None = None
+
+
+@router.get("")
+async def list_groups() -> GroupResponse:
+    """List all defined groups."""
+    manager = get_group_manager()
+    result = manager.list_groups()
+    return GroupResponse(**result)
+
+
+@router.get("/{name}")
+async def get_group(name: str) -> GroupResponse:
+    """Get a specific group by name."""
+    manager = get_group_manager()
+    result = manager.get_group(name)
+    if not result["success"]:
+        return GroupResponse(**result)
+    return GroupResponse(**result)
+
+
+@router.get("/{name}/status")
+async def get_group_status(name: str) -> GroupResponse:
+    """Get status of all processes in a group."""
+    manager = get_group_manager()
+    result = await manager.status_group(name)
+    return GroupResponse(**result)
+
+
+@router.post("/{name}/start")
+async def start_group(name: str) -> GroupResponse:
+    """Start all processes in a group in order."""
+    manager = get_group_manager()
+    result = await manager.start_group(name)
+    return GroupResponse(**result)
+
+
+@router.post("/{name}/stop")
+async def stop_group(name: str) -> GroupResponse:
+    """Stop all processes in a group in stop order."""
+    manager = get_group_manager()
+    result = await manager.stop_group(name)
+    return GroupResponse(**result)