procler 0.2.0__py3-none-any.whl

procler/core/recipes.py

@@ -0,0 +1,330 @@
+"""Recipe execution engine."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from ..config import (
+    ChangelogAction,
+    OnErrorAction,
+    RecipeDef,
+    RecipeStepExec,
+    RecipeStepGroupStart,
+    RecipeStepGroupStop,
+    RecipeStepRestart,
+    RecipeStepStart,
+    RecipeStepStop,
+    RecipeStepWait,
+    append_changelog,
+    get_config,
+)
+from . import get_process_manager
+from .events import EVENT_RECIPE_STEP, get_event_bus
+from .groups import get_group_manager
+
+
+class RecipeExecutor:
+    """Executes multi-step recipes."""
+
+    def __init__(self):
+        self._process_manager = get_process_manager()
+        self._group_manager = get_group_manager()
+
+    def list_recipes(self) -> dict[str, Any]:
+        """List all defined recipes."""
+        config = get_config()
+
+        recipes_data = []
+        for name, recipe in config.recipes.items():
+            recipes_data.append(
+                {
+                    "name": name,
+                    "description": recipe.description,
+                    "steps_count": len(recipe.steps),
+                    "on_error": recipe.on_error.value,
+                }
+            )
+
+        return {
+            "success": True,
+            "data": {
+                "recipes": recipes_data,
+                "count": len(recipes_data),
+            },
+        }
+
+    def get_recipe(self, name: str) -> dict[str, Any]:
+        """Get a specific recipe with full details."""
+        config = get_config()
+
+        if name not in config.recipes:
+            return {
+                "success": False,
+                "error": f"Recipe '{name}' not found",
+                "error_code": "recipe_not_found",
+                "suggestion": "Run 'procler recipe list' to see available recipes",
+            }
+
+        recipe = config.recipes[name]
+        return {
+            "success": True,
+            "data": {
+                "recipe": {
+                    "name": name,
+                    "description": recipe.description,
+                    "steps": recipe.steps,  # Raw steps for display
+                    "on_error": recipe.on_error.value,
+                }
+            },
+        }
+
+    async def run_recipe(
+        self,
+        name: str,
+        dry_run: bool = False,
+        continue_on_error: bool | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a recipe.
+
+        Args:
+            name: Recipe name
+            dry_run: If True, just show what would happen
+            continue_on_error: Override recipe's on_error setting
+        """
+        config = get_config()
+
+        if name not in config.recipes:
+            return {
+                "success": False,
+                "error": f"Recipe '{name}' not found",
+                "error_code": "recipe_not_found",
+                "suggestion": "Run 'procler recipe list' to see available recipes",
+            }
+
+        recipe = config.recipes[name]
+        steps = recipe.get_steps()
+
+        # Determine error handling behavior
+        if continue_on_error is not None:
+            should_continue = continue_on_error
+        else:
+            should_continue = recipe.on_error == OnErrorAction.CONTINUE
+
+        if dry_run:
+            return self._dry_run(name, recipe, steps)
+
+        # Execute for real
+        start_time = time.time()
+        results = []
+        all_success = True
+        stopped_at_step = None
+        total_steps = len(steps)
+
+        for i, step in enumerate(steps):
+            step_num = i + 1
+            action_desc = self._describe_step(step)
+
+            # Emit "running" event before execution
+            self._emit_step_event(name, step_num, total_steps, action_desc, "running")
+
+            step_result = await self._execute_step(step, step_num)
+            results.append(step_result)
+
+            # Determine status for event
+            if step_result["success"]:
+                status = "success"
+            elif step_result.get("ignore_error"):
+                status = "warning"
+            else:
+                status = "error"
+
+            # Emit completion event
+            self._emit_step_event(name, step_num, total_steps, action_desc, status, error=step_result.get("error"))
+
+            if not step_result["success"]:
+                all_success = False
+                if not should_continue and not step_result.get("ignore_error"):
+                    stopped_at_step = step_num
+                    # Emit skipped events for remaining steps
+                    for j in range(i + 1, len(steps)):
+                        skip_action = self._describe_step(steps[j])
+                        self._emit_step_event(name, j + 1, total_steps, skip_action, "skipped")
+                    break
+
+        duration_ms = int((time.time() - start_time) * 1000)
+
+        # Log execution to changelog
+        append_changelog(
+            action=ChangelogAction.EXECUTE,
+            entity_type="recipe",
+            entity_name=name,
+            details={
+                "duration_ms": duration_ms,
+                "success": all_success,
+                "steps_completed": len(results),
+                "stopped_at": stopped_at_step,
+            },
+        )
+
+        return {
+            "success": all_success,
+            "data": {
+                "recipe": name,
+                "duration_ms": duration_ms,
+                "steps_total": len(steps),
+                "steps_completed": len(results),
+                "stopped_at_step": stopped_at_step,
+                "results": results,
+            },
+        }
+
+    def _dry_run(self, name: str, recipe: RecipeDef, steps: list) -> dict[str, Any]:
+        """Show what a recipe would do without executing."""
+        planned_steps = []
+
+        for i, step in enumerate(steps):
+            planned_steps.append(
+                {
+                    "step": i + 1,
+                    "action": self._describe_step(step),
+                }
+            )
+
+        return {
+            "success": True,
+            "data": {
+                "recipe": name,
+                "description": recipe.description,
+                "dry_run": True,
+                "planned_steps": planned_steps,
+            },
+        }
+
+    def _emit_step_event(
+        self,
+        recipe: str,
+        step: int,
+        total: int,
+        action: str,
+        status: str,
+        error: str | None = None,
+    ) -> None:
+        """Emit a recipe step event for real-time updates."""
+        event_bus = get_event_bus()
+        event_bus.emit_sync(
+            EVENT_RECIPE_STEP,
+            {
+                "recipe": recipe,
+                "step": step,
+                "total": total,
+                "action": action,
+                "status": status,  # running, success, error, warning, skipped
+                "error": error,
+            },
+        )
+
+    def _describe_step(self, step) -> str:
+        """Get a human-readable description of a step."""
+        if isinstance(step, RecipeStepStart):
+            return f"start process '{step.start}'"
+        elif isinstance(step, RecipeStepStop):
+            suffix = " (ignore_error)" if step.ignore_error else ""
+            return f"stop process '{step.stop}'{suffix}"
+        elif isinstance(step, RecipeStepRestart):
+            return f"restart process '{step.restart}'"
+        elif isinstance(step, RecipeStepGroupStart):
+            return f"start group '{step.group_start}'"
+        elif isinstance(step, RecipeStepGroupStop):
+            return f"stop group '{step.group_stop}'"
+        elif isinstance(step, RecipeStepWait):
+            return f"wait {step.wait}"
+        elif isinstance(step, RecipeStepExec):
+            ctx = f" (docker:{step.container})" if step.container else ""
+            suffix = " (ignore_error)" if step.ignore_error else ""
+            return f"exec '{step.exec}'{ctx}{suffix}"
+        else:
+            return f"unknown step: {step}"
+
+    async def _execute_step(self, step, step_num: int) -> dict[str, Any]:
+        """Execute a single recipe step."""
+        result = {
+            "step": step_num,
+            "action": self._describe_step(step),
+            "success": True,
+        }
+
+        try:
+            if isinstance(step, RecipeStepStart):
+                res = await self._process_manager.start(step.start)
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+
+            elif isinstance(step, RecipeStepStop):
+                res = await self._process_manager.stop(step.stop)
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+                result["ignore_error"] = step.ignore_error
+
+            elif isinstance(step, RecipeStepRestart):
+                res = await self._process_manager.restart(step.restart)
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+
+            elif isinstance(step, RecipeStepGroupStart):
+                res = await self._group_manager.start_group(step.group_start)
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+
+            elif isinstance(step, RecipeStepGroupStop):
+                res = await self._group_manager.stop_group(step.group_stop)
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+
+            elif isinstance(step, RecipeStepWait):
+                seconds = step.get_seconds()
+                await asyncio.sleep(seconds)
+                result["details"] = {"waited_seconds": seconds}
+
+            elif isinstance(step, RecipeStepExec):
+                timeout = step.get_timeout_seconds()
+                res = await self._process_manager.exec_command(
+                    command=step.exec,
+                    context_type=step.context.value,
+                    container_name=step.container,
+                    cwd=step.cwd,
+                    timeout=timeout,
+                )
+                result["success"] = res["success"]
+                result["details"] = res.get("data") or {"error": res.get("error")}
+                result["ignore_error"] = step.ignore_error
+
+            else:
+                result["success"] = False
+                result["error"] = f"Unknown step type: {type(step)}"
+
+        except Exception as e:
+            result["success"] = False
+            result["error"] = str(e)
+
+        return result
+
+
+# Singleton
+_recipe_executor: RecipeExecutor | None = None
+
+
+def get_recipe_executor() -> RecipeExecutor:
+    """Get the singleton RecipeExecutor instance."""
+    global _recipe_executor
+    if _recipe_executor is None:
+        _recipe_executor = RecipeExecutor()
+    return _recipe_executor
+
+
+def reset_recipe_executor() -> None:
+    """Reset the singleton (for testing)."""
+    global _recipe_executor
+    _recipe_executor = None

procler/core/snippets.py

@@ -0,0 +1,231 @@
+"""Snippet management for reusable commands."""
+
+from datetime import datetime
+from typing import Any
+
+from sqler.query import SQLerField as F
+
+from ..db import init_database
+from ..models import Snippet
+from .context_docker import is_docker_available
+from .context_local import get_local_context
+from .variable_substitution import substitute_vars_from_config
+
+
+class SnippetManager:
+    """Manager for command snippets."""
+
+    def __init__(self):
+        pass
+
+    def _get_snippet_by_name(self, name: str) -> Snippet | None:
+        """Get a snippet by name."""
+        init_database()
+        results = Snippet.query().filter(F("name") == name).all()
+        return results[0] if results else None
+
+    def _snippet_to_dict(self, snippet: Snippet) -> dict[str, Any]:
+        """Convert a Snippet to a dict for JSON output."""
+        return {
+            "id": snippet._id,
+            "name": snippet.name,
+            "command": snippet.command,
+            "description": snippet.description,
+            "context_type": snippet.context_type,
+            "container_name": snippet.container_name,
+            "tags": snippet.tags or [],
+            "created_at": snippet.created_at,
+        }
+
+    def list_snippets(self, tag: str | None = None) -> dict[str, Any]:
+        """
+        List all snippets, optionally filtered by tag.
+
+        Args:
+            tag: Optional tag to filter by
+
+        Returns a dict with snippet list (for JSON output).
+        """
+        init_database()
+
+        snippets = Snippet.query().all()
+
+        if tag:
+            # Filter by tag
+            snippets = [s for s in snippets if s.tags and tag in s.tags]
+
+        return {
+            "success": True,
+            "data": {
+                "snippets": [self._snippet_to_dict(s) for s in snippets],
+                "count": len(snippets),
+            },
+        }
+
+    def save_snippet(
+        self,
+        name: str,
+        command: str,
+        description: str | None = None,
+        context_type: str = "local",
+        container_name: str | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Save a new snippet.
+
+        Args:
+            name: Unique snippet name
+            command: Command to execute
+            description: Optional description
+            context_type: Execution context ('local' or 'docker')
+            container_name: Docker container name (required if context=docker)
+            tags: Optional list of tags
+
+        Returns a dict with save result (for JSON output).
+        """
+        init_database()
+
+        # Validate docker context
+        if context_type == "docker" and not container_name:
+            return {
+                "success": False,
+                "error": "Container name required for docker context",
+                "error_code": "missing_container",
+                "suggestion": "Use --container <name> to specify the Docker container",
+            }
+
+        # Check if snippet already exists
+        existing = self._get_snippet_by_name(name)
+        if existing:
+            return {
+                "success": False,
+                "error": f"Snippet '{name}' already exists",
+                "error_code": "snippet_exists",
+                "suggestion": f"Use 'procler snippet remove {name}' first, or choose a different name",
+            }
+
+        snippet = Snippet(
+            name=name,
+            command=command,
+            description=description,
+            context_type=context_type,
+            container_name=container_name,
+            tags=tags,
+            created_at=datetime.now().isoformat(),
+        )
+        snippet.save()
+
+        return {
+            "success": True,
+            "data": {
+                "action": "created",
+                "snippet": self._snippet_to_dict(snippet),
+            },
+        }
+
+    def remove_snippet(self, name: str) -> dict[str, Any]:
+        """
+        Remove a snippet by name.
+
+        Returns a dict with removal result (for JSON output).
+        """
+        init_database()
+
+        snippet = self._get_snippet_by_name(name)
+        if not snippet:
+            return {
+                "success": False,
+                "error": f"Snippet '{name}' not found",
+                "error_code": "snippet_not_found",
+                "suggestion": "Run 'procler snippet list' to see available snippets",
+            }
+
+        snippet.delete()
+
+        return {
+            "success": True,
+            "data": {
+                "action": "removed",
+                "name": name,
+            },
+        }
+
+    async def run_snippet(self, name: str) -> dict[str, Any]:
+        """
+        Run a snippet by name.
+
+        Returns a dict with execution result (for JSON output).
+        """
+        init_database()
+
+        snippet = self._get_snippet_by_name(name)
+        if not snippet:
+            return {
+                "success": False,
+                "error": f"Snippet '{name}' not found",
+                "error_code": "snippet_not_found",
+                "suggestion": "Run 'procler snippet list' to see available snippets",
+            }
+
+        # Substitute config vars in command (e.g., ${SIM_CONTAINER})
+        resolved_command = substitute_vars_from_config(snippet.command)
+
+        # Validate docker context
+        if snippet.context_type == "docker":
+            if not snippet.container_name:
+                return {
+                    "success": False,
+                    "error": "Snippet has docker context but no container name",
+                    "error_code": "missing_container",
+                }
+
+            if not is_docker_available():
+                return {
+                    "success": False,
+                    "error": "Docker is not available",
+                    "error_code": "docker_unavailable",
+                    "suggestion": "Ensure Docker is installed and running",
+                }
+
+            # Import here to avoid circular imports
+            from .context_docker import get_docker_context
+
+            context = get_docker_context()
+            try:
+                result = await context.exec_command(
+                    command=resolved_command,
+                    container_name=snippet.container_name,
+                )
+            except ValueError as e:
+                return {
+                    "success": False,
+                    "error": str(e),
+                    "error_code": "container_not_found",
+                }
+        else:
+            # Local context
+            context = get_local_context()
+            result = await context.exec_command(command=resolved_command)
+
+        return {
+            "success": True,
+            "data": {
+                "snippet": name,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "exit_code": result.exit_code,
+            },
+        }
+
+
+# Global singleton
+_snippet_manager: SnippetManager | None = None
+
+
+def get_snippet_manager() -> SnippetManager:
+    """Get the global SnippetManager instance."""
+    global _snippet_manager
+    if _snippet_manager is None:
+        _snippet_manager = SnippetManager()
+    return _snippet_manager

procler/core/variable_substitution.py

@@ -0,0 +1,65 @@
+"""Variable substitution for procler commands.
+
+Replaces ${VAR} patterns in commands with values from config.vars.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# Patterns that might indicate shell injection
+SUSPICIOUS_PATTERNS = [";", "&&", "||", "$(", "`", "\n"]
+
+
+def warn_suspicious_vars(vars: dict[str, str]) -> None:
+    """Log warnings for vars containing suspicious patterns."""
+    for name, value in vars.items():
+        for pattern in SUSPICIOUS_PATTERNS:
+            if pattern in value:
+                logger.warning(
+                    f"Variable '{name}' contains suspicious pattern '{pattern}'. " f"Ensure this is intentional."
+                )
+                break
+
+
+def substitute_vars(text: str, vars: dict[str, str]) -> str:
+    """
+    Replace ${VAR} patterns with values from vars dict.
+
+    If a variable is not found, the original ${VAR} pattern is kept.
+
+    Args:
+        text: String containing ${VAR} patterns
+        vars: Dict mapping variable names to values
+
+    Returns:
+        String with variables substituted
+    """
+    if not vars:
+        return text
+
+    def replacer(match: re.Match) -> str:
+        var_name = match.group(1)
+        if var_name in vars:
+            return vars[var_name]
+        # Keep original if not found
+        return match.group(0)
+
+    # Match ${VAR_NAME} pattern (alphanumeric and underscore)
+    return re.sub(r"\$\{(\w+)\}", replacer, text)
+
+
+def substitute_vars_from_config(text: str) -> str:
+    """
+    Replace ${VAR} patterns with values from config.vars.
+
+    Convenience function that loads vars from the current config.
+    """
+    # Import here to avoid circular dependency
+    from procler.config.loader import get_config
+
+    config = get_config()
+    return substitute_vars(text, config.vars)