procler 0.2.0__py3-none-any.whl

procler/config/__init__.py

@@ -0,0 +1,65 @@
+"""Configuration management for procler."""
+
+from .changelog import ChangelogAction, append_changelog, read_changelog
+from .loader import (
+    find_config_dir,
+    generate_template_config,
+    get_changelog_path,
+    get_config,
+    get_config_file_path,
+    get_state_db_path,
+    load_config,
+    reload_config,
+)
+from .schema import (
+    ContextType,
+    DependencyCondition,
+    DependencyDef,
+    GroupDef,
+    HealthCheckDef,
+    OnErrorAction,
+    ProcessDef,
+    ProclerConfig,
+    RecipeDef,
+    RecipeStep,
+    RecipeStepExec,
+    RecipeStepGroupStart,
+    RecipeStepGroupStop,
+    RecipeStepRestart,
+    RecipeStepStart,
+    RecipeStepStop,
+    RecipeStepWait,
+    SnippetDef,
+)
+
+__all__ = [
+    "find_config_dir",
+    "load_config",
+    "get_config",
+    "reload_config",
+    "generate_template_config",
+    "get_config_file_path",
+    "get_changelog_path",
+    "get_state_db_path",
+    "ProclerConfig",
+    "ProcessDef",
+    "GroupDef",
+    "RecipeDef",
+    "RecipeStep",
+    "SnippetDef",
+    "OnErrorAction",
+    "ContextType",
+    "RecipeStepStart",
+    "RecipeStepStop",
+    "RecipeStepRestart",
+    "RecipeStepGroupStart",
+    "RecipeStepGroupStop",
+    "RecipeStepWait",
+    "RecipeStepExec",
+    "HealthCheckDef",
+    "DependencyCondition",
+    "DependencyDef",
+    "append_changelog",
+    "read_changelog",
+    "ChangelogAction",
+]

procler/config/changelog.py

@@ -0,0 +1,148 @@
+"""Append-only changelog for tracking config changes."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from .loader import get_changelog_path
+
+
+class ChangelogAction(str, Enum):
+    """Types of changelog actions."""
+
+    CREATE = "CREATE"
+    UPDATE = "UPDATE"
+    DELETE = "DELETE"
+    EXECUTE = "EXECUTE"  # For recipe executions
+    START = "START"  # Process started
+    STOP = "STOP"  # Process stopped
+
+
+def append_changelog(
+    action: ChangelogAction,
+    entity_type: str,
+    entity_name: str,
+    details: dict[str, Any] | None = None,
+    changelog_path: Path | None = None,
+) -> None:
+    """
+    Append an entry to the changelog.
+
+    Format: [ISO8601] ACTION type:name {json_details}
+
+    Args:
+        action: The action performed (CREATE, UPDATE, DELETE, EXECUTE, START, STOP)
+        entity_type: Type of entity (process, group, recipe, snippet)
+        entity_name: Name of the entity
+        details: Optional dict of additional details
+        changelog_path: Override path for testing
+    """
+    try:
+        if changelog_path is None:
+            changelog_path = get_changelog_path()
+    except (ValueError, FileNotFoundError):
+        # No config directory found - skip logging silently
+        return
+
+    # Ensure directory exists
+    changelog_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create header if file doesn't exist
+    if not changelog_path.exists():
+        header = (
+            "# Procler Changelog - AUTO-GENERATED\n"
+            "# DO NOT EDIT MANUALLY\n"
+            "# Format: [ISO8601] ACTION type:name {json_details}\n"
+            "#\n"
+        )
+        changelog_path.write_text(header)
+
+    # Build log entry
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    details_json = json.dumps(details or {}, separators=(",", ":"))
+    entry = f"[{timestamp}] {action.value} {entity_type}:{entity_name} {details_json}\n"
+
+    # Append to file
+    with open(changelog_path, "a") as f:
+        f.write(entry)
+
+
+def read_changelog(changelog_path: Path | None = None) -> list[dict[str, Any]]:
+    """
+    Read and parse the changelog.
+
+    Returns list of entries:
+    [
+        {
+            "timestamp": "2024-01-08T12:00:00Z",
+            "action": "CREATE",
+            "entity_type": "process",
+            "entity_name": "api",
+            "details": {...}
+        },
+        ...
+    ]
+    """
+    if changelog_path is None:
+        changelog_path = get_changelog_path()
+
+    if not changelog_path.exists():
+        return []
+
+    entries = []
+    for line in changelog_path.read_text().splitlines():
+        line = line.strip()
+        # Skip comments and empty lines
+        if not line or line.startswith("#"):
+            continue
+
+        try:
+            # Parse: [TIMESTAMP] ACTION type:name {json}
+            # Find the timestamp
+            ts_end = line.index("]")
+            timestamp = line[1:ts_end]
+
+            # Find the action
+            rest = line[ts_end + 2 :]  # Skip "] "
+            parts = rest.split(" ", 2)
+            if len(parts) < 2:
+                continue
+
+            action = parts[0]
+            entity = parts[1]
+            details_str = parts[2] if len(parts) > 2 else "{}"
+
+            # Parse entity type:name
+            entity_type, _, entity_name = entity.partition(":")
+
+            # Parse details JSON
+            details = json.loads(details_str)
+
+            entries.append(
+                {
+                    "timestamp": timestamp,
+                    "action": action,
+                    "entity_type": entity_type,
+                    "entity_name": entity_name,
+                    "details": details,
+                }
+            )
+        except (ValueError, json.JSONDecodeError):
+            # Skip malformed lines
+            continue
+
+    return entries
+
+
+def get_entity_history(
+    entity_type: str,
+    entity_name: str,
+    changelog_path: Path | None = None,
+) -> list[dict[str, Any]]:
+    """Get changelog entries for a specific entity."""
+    entries = read_changelog(changelog_path)
+    return [e for e in entries if e["entity_type"] == entity_type and e["entity_name"] == entity_name]

procler/config/loader.py

@@ -0,0 +1,256 @@
+"""Config file discovery and loading."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from .schema import ProclerConfig
+
+# Singleton config cache
+_config_cache: ProclerConfig | None = None
+_config_dir_cache: Path | None = None
+
+
+def find_git_root() -> Path | None:
+    """Find the root of the git repository, if any."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return Path(result.stdout.strip())
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return None
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    """Parse a simple .env file (KEY=value format)."""
+    env = {}
+    if path.exists():
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, _, value = line.partition("=")
+                # Strip quotes if present
+                value = value.strip().strip('"').strip("'")
+                env[key.strip()] = value
+    return env
+
+
+def find_config_dir(start_dir: Path | None = None) -> Path:
+    """
+    Find the procler config directory using this discovery chain:
+
+    1. PROCLER_CONFIG_DIR environment variable
+    2. .procler.env file in current dir or parents (sets PROCLER_CONFIG_DIR)
+    3. .procler/ directory in current dir
+    4. .procler/ directory in git root
+    5. ~/.procler/ (global fallback)
+    """
+    global _config_dir_cache
+    if _config_dir_cache is not None:
+        return _config_dir_cache
+
+    start = start_dir or Path.cwd()
+
+    # 1. Explicit environment variable
+    if env_dir := os.environ.get("PROCLER_CONFIG_DIR"):
+        _config_dir_cache = Path(env_dir).expanduser().resolve()
+        return _config_dir_cache
+
+    # 2. Search for .procler.env in current dir and parents
+    for parent in [start] + list(start.parents):
+        env_file = parent / ".procler.env"
+        if env_file.exists():
+            env = parse_env_file(env_file)
+            if config_dir := env.get("PROCLER_CONFIG_DIR"):
+                # Resolve relative to the .procler.env location
+                resolved = (parent / config_dir).resolve()
+                _config_dir_cache = resolved
+                return _config_dir_cache
+
+    # 3. .procler/ in current directory
+    local_config = start / ".procler"
+    if local_config.exists() and local_config.is_dir():
+        _config_dir_cache = local_config
+        return _config_dir_cache
+
+    # 4. .procler/ in git root
+    git_root = find_git_root()
+    if git_root:
+        git_config = git_root / ".procler"
+        if git_config.exists() and git_config.is_dir():
+            _config_dir_cache = git_config
+            return _config_dir_cache
+
+    # 5. Global fallback
+    _config_dir_cache = Path.home() / ".procler"
+    return _config_dir_cache
+
+
+def get_config_file_path() -> Path:
+    """Get the path to the config.yaml file."""
+    return find_config_dir() / "config.yaml"
+
+
+def get_changelog_path() -> Path:
+    """Get the path to the changelog.log file."""
+    return find_config_dir() / "changelog.log"
+
+
+def get_state_db_path() -> Path:
+    """Get the path to the state.db file."""
+    return find_config_dir() / "state.db"
+
+
+def load_config(config_path: Path | None = None) -> ProclerConfig:
+    """
+    Load configuration from YAML file.
+
+    Returns an empty config if no config file exists.
+    """
+    global _config_cache
+
+    if config_path is None:
+        config_path = get_config_file_path()
+
+    if not config_path.exists():
+        # Return empty config - processes/groups/recipes can be empty
+        return ProclerConfig()
+
+    with open(config_path) as f:
+        data = yaml.safe_load(f) or {}
+
+    config = ProclerConfig.model_validate(data)
+
+    # Warn about suspicious patterns in vars (security check)
+    if config.vars:
+        from ..core.variable_substitution import warn_suspicious_vars
+
+        warn_suspicious_vars(config.vars)
+
+    _config_cache = config
+    return config
+
+
+def get_config() -> ProclerConfig:
+    """Get the cached config, loading if necessary."""
+    global _config_cache
+    if _config_cache is None:
+        _config_cache = load_config()
+    return _config_cache
+
+
+def reload_config() -> ProclerConfig:
+    """Force reload of config from disk."""
+    global _config_cache
+    _config_cache = None
+    return load_config()
+
+
+def save_config(config: ProclerConfig, config_path: Path | None = None) -> None:
+    """Save configuration to YAML file."""
+    if config_path is None:
+        config_path = get_config_file_path()
+
+    # Ensure directory exists
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Convert to dict, excluding defaults for cleaner output
+    data = config.model_dump(exclude_defaults=True, exclude_none=True)
+
+    # Always include version
+    data["version"] = config.version
+
+    with open(config_path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def reset_config_cache() -> None:
+    """Reset the config cache (useful for testing)."""
+    global _config_cache, _config_dir_cache
+    _config_cache = None
+    _config_dir_cache = None
+
+
+def generate_template_config() -> str:
+    """Generate a template config.yaml with examples."""
+    return """\
+# Procler Configuration - LLM-First Process Manager
+# https://github.com/gabu-quest/procler
+#
+# This file is VERSION CONTROLLED - commit it to your repo!
+# Each project can have its own .procler/ directory.
+#
+# Files in .procler/:
+#   config.yaml   - This file (commit to git)
+#   changelog.log - Audit trail of operations (commit to git)
+#   state.db      - Runtime state (auto-gitignored)
+#
+# Discovery order: $PROCLER_CONFIG_DIR > .procler.env > .procler/ > git root > ~/.procler/
+#
+# CLI: `procler config explain` shows what this config does in plain language
+# API: GET /api/config/explain returns the same as JSON
+version: 1
+
+# Process definitions - things that run continuously
+processes:
+  # Example local process
+  # api:
+  #   command: uvicorn main:app --reload
+  #   context: local
+  #   cwd: /path/to/project
+  #   tags: [backend, api]
+  #   description: "FastAPI development server"
+  #
+  # Example docker process
+  # worker:
+  #   command: celery -A app worker
+  #   context: docker
+  #   container: my-container
+  #   description: "Background task worker"
+
+# Process groups - ordered start/stop
+# Use: `procler group start backend` / `procler group stop backend`
+groups:
+  # Example group
+  # backend:
+  #   description: "Full backend stack"
+  #   processes: [redis, api, worker]  # Start in this order
+  #   # stop_order defaults to reverse of processes
+  #   # stop_order: [worker, api, redis]  # Custom stop order
+
+# Recipes - multi-step operations (like makefiles for processes)
+# Use: `procler recipe run deploy --dry-run` to preview
+recipes:
+  # Example recipe
+  # deploy:
+  #   description: "Graceful deployment with migration"
+  #   on_error: stop  # or "continue"
+  #   steps:
+  #     - stop: worker
+  #     - stop: api
+  #     - wait: 2s
+  #     - exec: "alembic upgrade head"
+  #       context: docker
+  #       container: my-container
+  #     - start: api
+  #     - start: worker
+
+# Snippets - reusable one-off commands
+# Use: `procler snippet run rebuild`
+snippets:
+  # Example snippet
+  # rebuild:
+  #   command: docker compose build
+  #   description: "Rebuild all containers"
+  #   tags: [docker, build]
+"""