mxx-tool 0.1.0__py3-none-any.whl

mxx/runner/builtins/mxxrun.py

@@ -0,0 +1,158 @@
+
+
+
+"""
+MXX App Runner plugin for launching registered applications.
+
+This plugin loads applications from the MXX app registry and launches them
+with proper configuration override handling.
+"""
+
+import os
+import subprocess
+from pathlib import Path
+from mxx.runner.core.plugin import MxxPlugin, hook
+from mxx.cfg_tool.registry import get_app_by_name, load_json_config, save_json_config
+from mxx.utils.nested import nested_set
+
+
+class MxxRun(MxxPlugin):
+    """
+    Registered application launcher plugin.
+    
+    Loads applications from the MXX app registry (~/.mxx/apps) and launches them
+    with configuration overrides applied. Supports automatic config modification
+    and application termination.
+    
+    Config Key: "mxxrun"
+    
+    Example Configuration:
+        ```toml
+        [mxxrun]
+        app_name = "myapp"  # Name/alias from registry
+        temp_config = true  # Optional: use temporary config copy
+        ```
+    """
+    
+    __cmdname__ = "mxxrun"
+
+    def __init__(self, app_name: str = None, temp_config: bool = False, **kwargs):
+        super().__init__()
+        self.app_name = app_name
+        self.temp_config = temp_config
+        self.app_info = None
+        self.executable_path = None
+        self.config_path = None
+        self.original_config_path = None
+        
+        # Validation
+        if not self.app_name:
+            raise ValueError("app_name must be specified for MxxRun configuration.")
+
+    @hook("pre_action")
+    def load_and_prepare_app(self, runner):
+        """
+        Load app from registry and prepare configuration with overrides.
+        
+        Raises:
+            ValueError: If app not found in registry
+            FileNotFoundError: If app executable or config not found
+        """
+        # Load app from registry
+        self.app_info = get_app_by_name(self.app_name)
+        if not self.app_info:
+            raise ValueError(f"Application '{self.app_name}' not found in MXX registry")
+        
+        app_config = self.app_info["config"]
+        
+        # Resolve paths from registry
+        app_path = Path(app_config["path"])
+        self.executable_path = app_path / app_config["app"]
+        self.original_config_path = app_path / app_config["cfgroute"]
+        
+        # Validate paths exist
+        if not self.executable_path.exists():
+            raise FileNotFoundError(f"App executable not found at {self.executable_path}")
+        if not self.original_config_path.exists():
+            raise FileNotFoundError(f"App config folder not found at {self.original_config_path}")
+        
+        # Apply config overrides if any exist
+        if app_config.get("cfgow"):
+            self._apply_config_overrides(app_config["cfgow"])
+
+    def _apply_config_overrides(self, overrides):
+        """
+        Apply configuration overrides to all JSON files in config folder.
+        
+        Args:
+            overrides: Dictionary of nested key->value overrides
+        """
+        import shutil
+        import tempfile
+        
+        if self.temp_config:
+            # Create temporary config copy
+            temp_dir = Path(tempfile.mkdtemp(prefix="mxx_config_"))
+            shutil.copytree(self.original_config_path, temp_dir / "config")
+            self.config_path = temp_dir / "config"
+        else:
+            # Modify original config in place
+            self.config_path = self.original_config_path
+        
+        # Apply overrides to all JSON files
+        for json_file in self.config_path.rglob("*.json"):
+            try:
+                config_data = load_json_config(json_file)
+                
+                # Apply each override
+                for override_key, override_value in overrides.items():
+                    nested_set(config_data, override_key, override_value)
+                
+                # Save modified config
+                save_json_config(json_file, config_data)
+                
+            except Exception as e:
+                print(f"Warning: Could not apply overrides to {json_file.name}: {e}")
+
+    @hook("action")
+    def launch_application(self, runner):
+        """
+        Launch the registered application in detached mode.
+        """
+        self._open_detached([str(self.executable_path)])
+
+    @hook("post_action")
+    def cleanup(self, runner):
+        """
+        Clean up temporary files and terminate the application.
+        """
+        # Clean up temporary config if used
+        if self.temp_config and self.config_path and self.config_path != self.original_config_path:
+            import shutil
+            try:
+                shutil.rmtree(self.config_path.parent)
+            except Exception as e:
+                print(f"Warning: Could not clean up temporary config: {e}")
+        
+        # Terminate the application using executable name from registry
+        if self.app_info:
+            executable_name = Path(self.app_info["config"]["app"]).name
+            os.system(f"taskkill /IM {executable_name} /F")
+
+    @staticmethod
+    def _open_detached(args):
+        """
+        Open a process in detached mode (doesn't block).
+        
+        Args:
+            args: List of command arguments, first element is the executable path
+        """
+        DETACHED_PROCESS = 0x00000008
+        subprocess.Popen(
+            args,
+            creationflags=DETACHED_PROCESS,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL
+        )
+

mxx/runner/builtins/mxxset.py

@@ -0,0 +1,171 @@
+"""
+MXX Config Set plugin for importing configurations to registered applications.
+
+This plugin imports configuration folders/files to registered applications,
+similar to the mxx cfg import command but usable within runner workflows.
+"""
+
+from pathlib import Path
+from mxx.runner.core.plugin import MxxPlugin, hook
+from mxx.cfg_tool.registry import get_app_by_name, load_json_config, save_json_config
+from mxx.utils.nested import nested_get, nested_set
+
+
+class MxxSet(MxxPlugin):
+    """
+    Configuration import plugin for registered applications.
+    
+    Imports and merges configuration folders for registered applications,
+    preserving excluded keys and applying overrides. This provides the same
+    functionality as `mxx cfg import` but within runner workflows.
+    
+    Config Key: "mxxset"
+    
+    Example Configuration:
+        ```toml
+        [mxxset]
+        app_name = "myapp"           # Name/alias from registry
+        import_source = "backup1"    # Import folder (relative to exports or absolute)
+        ```
+    """
+    
+    __cmdname__ = "mxxset"
+
+    def __init__(self, app_name: str = None, import_source: str = None, **kwargs):
+        super().__init__()
+        self.app_name = app_name
+        self.import_source = import_source
+        self.app_info = None
+        
+        # Validation
+        if not self.app_name:
+            raise ValueError("app_name must be specified for MxxSet configuration.")
+        if not self.import_source:
+            raise ValueError("import_source must be specified for MxxSet configuration.")
+
+    @hook("action")
+    def import_configuration(self, runner):
+        """
+        Import and merge configuration for the registered application.
+        
+        Loads the app from registry, resolves import source path, and performs
+        the same smart merge as the cfg import command.
+        
+        Raises:
+            ValueError: If app not found in registry
+            FileNotFoundError: If import source not found
+        """
+        # Load app from registry
+        self.app_info = get_app_by_name(self.app_name)
+        if not self.app_info:
+            raise ValueError(f"Application '{self.app_name}' not found in MXX registry")
+        
+        app_config = self.app_info["config"]
+        uid = self.app_info["uid"]
+        
+        # Get target config folder path
+        target_config_folder = Path(app_config["path"]) / app_config["cfgroute"]
+        
+        # Resolve import path - first try relative to app's exports directory
+        import_path = self._resolve_import_path(uid)
+        
+        if not import_path.exists():
+            raise FileNotFoundError(f"Import source not found at {import_path}")
+        
+        if not import_path.is_dir():
+            raise ValueError(f"Import source is not a directory: {import_path}")
+        
+        # Ensure target config folder exists
+        target_config_folder.mkdir(parents=True, exist_ok=True)
+        
+        # Import configuration
+        self._import_config_folder(import_path, target_config_folder, app_config)
+
+    def _resolve_import_path(self, uid: str) -> Path:
+        """
+        Resolve import source path, trying exports directory first.
+        
+        Args:
+            uid: App UID for exports directory resolution
+            
+        Returns:
+            Resolved Path object
+        """
+        import_path = Path(self.import_source)
+        
+        # If not absolute, try relative to app's exports directory first
+        if not import_path.is_absolute():
+            app_exports_dir = Path.home() / ".mxx" / "exports" / uid
+            relative_import_path = app_exports_dir / self.import_source
+            
+            if relative_import_path.exists() and relative_import_path.is_dir():
+                return relative_import_path
+        
+        return import_path
+
+    def _import_config_folder(self, import_path: Path, target_path: Path, app_config: dict):
+        """
+        Import configuration folder with smart merging.
+        
+        Args:
+            import_path: Source folder to import from
+            target_path: Target folder to import to
+            app_config: App configuration containing cfge and cfgow settings
+        """
+        processed_files = 0
+        total_preserved = 0
+        
+        # Process all JSON files in the import folder
+        for import_json_file in import_path.rglob("*.json"):
+            try:
+                # Get relative path to maintain folder structure
+                rel_path = import_json_file.relative_to(import_path)
+                target_json_file = target_path / rel_path
+                
+                # Ensure target directory exists
+                target_json_file.parent.mkdir(parents=True, exist_ok=True)
+                
+                # Load import data
+                import_config_data = load_json_config(import_json_file)
+                
+                # Load existing target config or create empty
+                if target_json_file.exists():
+                    target_config = load_json_config(target_json_file)
+                else:
+                    target_config = {}
+                
+                # Preserve excluded keys (cfge) from target
+                preserved_values = {}
+                if "cfge" in app_config:
+                    for exclude_key in app_config["cfge"]:
+                        value = nested_get(target_config, exclude_key)
+                        if value is not None:
+                            preserved_values[exclude_key] = value
+                
+                # Update target config with imported data
+                target_config.update(import_config_data)
+                
+                # Restore preserved excluded keys
+                for key, value in preserved_values.items():
+                    nested_set(target_config, key, value)
+                
+                # Apply overrides (cfgow)
+                if "cfgow" in app_config:
+                    for override_key, override_value in app_config["cfgow"].items():
+                        nested_set(target_config, override_key, override_value)
+                
+                # Save updated config
+                save_json_config(target_json_file, target_config)
+                
+                processed_files += 1
+                total_preserved += len(preserved_values)
+                
+            except Exception as e:
+                print(f"Warning: Could not process {import_json_file.name}: {e}")
+        
+        print(f"MxxSet imported configuration for '{self.app_name}':")
+        print(f"  Source: {import_path}")
+        print(f"  Target: {target_path}")
+        print(f"  Processed {processed_files} JSON files")
+        print(f"  Preserved {total_preserved} excluded keys")
+        print(f"  Applied {len(app_config.get('cfgow', {}))} override patterns")

mxx/runner/builtins/os_exec.py

@@ -0,0 +1,78 @@
+"""
+OS command execution plugin for running arbitrary system commands.
+
+This plugin executes system commands at startup and optionally registers
+processes for cleanup via the lifetime plugin.
+"""
+
+import os
+from mxx.runner.core.plugin import MxxPlugin, hook
+
+
+class OSExec(MxxPlugin):
+    """
+    System command execution plugin.
+    
+    Executes arbitrary OS commands at startup and optionally registers
+    processes for cleanup when the lifetime plugin is present.
+    
+    Config Key: "os"
+    
+    Features:
+        - Execute any system command via os.system()
+        - Register processes for automatic cleanup on shutdown
+        - Integrates with lifetime plugin for process management
+    
+    Example Configuration:
+        ```toml
+        [os]
+        cmd = "start C:/Tools/monitor.exe"
+        kill = "monitor.exe"
+        
+        [lifetime]
+        lifetime = 3600
+        ```
+    
+    Notes:
+        - Commands are executed synchronously
+        - If 'kill' is specified and lifetime plugin is loaded, the process
+          will be added to the lifetime plugin's kill list
+        - Supports both simple process names and commands with arguments
+    """
+    
+    __cmdname__ = "os"
+
+    def __init__(self, cmd: str = None, kill: str = None, **kwargs):
+        super().__init__()
+        self.cmd = cmd
+        self.kill = kill
+
+    @hook("action")
+    def execute_command(self, runner):
+        """
+        Execute the configured system command.
+        
+        If a kill target is specified and the lifetime plugin is loaded,
+        registers the process for automatic termination on shutdown.
+        """
+        if self.cmd:
+            os.system(self.cmd)
+            
+            # Try to register with lifetime plugin if it exists
+            if self.kill:
+                lifetime_plugin = self._find_lifetime_plugin(runner)
+                if lifetime_plugin:
+                    if " " in self.kill:
+                        lifetime_plugin.killList.append(("cmd", self.kill.split(" ")[0]))
+                    else:
+                        lifetime_plugin.killList.append(("process", self.kill))
+
+    def _find_lifetime_plugin(self, runner):
+        """Find the lifetime plugin in the runner's plugins."""
+        from mxx.runner.builtins.lifetime import Lifetime
+        
+        if hasattr(runner, 'plugins'):
+            for plugin in runner.plugins.values():
+                if isinstance(plugin, Lifetime):
+                    return plugin
+        return None

mxx/runner/core/callstack.py

@@ -0,0 +1,45 @@
+
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MxxCallstack:
+    any_cond : list[callable] = field(default_factory=list)
+    all_cond : list[callable] = field(default_factory=list)
+    action : list[callable] = field(default_factory=list)
+    pre_action : list[callable] = field(default_factory=list)
+    post_action : list[callable] = field(default_factory=list)
+    on_true : list[callable] = field(default_factory=list)
+    on_false : list[callable] = field(default_factory=list)
+    on_error : list[callable] = field(default_factory=list)
+
+    def merge(self, other : "MxxCallstack"):
+        for hook_type in self.__dataclass_fields__.keys():
+            getattr(self, hook_type).extend(getattr(other, hook_type))
+
+class PluginCallstackMeta(type):
+    _callstackMap : dict[str, MxxCallstack] = {}
+
+    def __call__(cls, *args, **kwargs):
+        instance = super().__call__(*args, **kwargs)
+
+        if instance.__cmdname__ in cls._callstackMap:
+            raise Exception(f"Callstack for plugin '{instance.__cmdname__}' is already created")
+        
+        callstack = MxxCallstack()
+        cls._callstackMap[instance.__cmdname__] = callstack
+
+        # map all hook functions to the callstack
+        for attr_name in dir(instance):
+            attr = getattr(instance, attr_name)
+            if callable(attr) and hasattr(attr, "_mxx_hook_types"):
+                hook_type = attr._mxx_hook_types
+                if hasattr(callstack, hook_type):
+                    getattr(callstack, hook_type).append(attr)
+                else:
+                    raise Exception(f"Invalid hook type '{hook_type}' for function '{attr_name}'")
+
+        return instance
+    
+    

mxx/runner/core/config_loader.py

@@ -0,0 +1,84 @@
+"""
+Configuration file loader for MXX runner.
+
+Supports loading configuration from YAML, TOML, and JSON files.
+Auto-detects format based on file extension.
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+
+def load_config(filepath: str | Path) -> Dict[str, Any]:
+    """
+    Load configuration from a file.
+    
+    Supports:
+    - YAML (.yaml, .yml)
+    - TOML (.toml)
+    - JSON (.json)
+    
+    Args:
+        filepath: Path to configuration file
+        
+    Returns:
+        Configuration dictionary
+        
+    Raises:
+        FileNotFoundError: If config file doesn't exist
+        ValueError: If file format is unsupported
+        ImportError: If required library for format is not installed
+    """
+    path = Path(filepath)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {filepath}")
+    
+    suffix = path.suffix.lower()
+    
+    if suffix == '.json':
+        return _load_json(path)
+    elif suffix == '.toml':
+        return _load_toml(path)
+    elif suffix in ['.yaml', '.yml']:
+        return _load_yaml(path)
+    else:
+        raise ValueError(f"Unsupported config file format: {suffix}")
+
+
+def _load_json(path: Path) -> Dict[str, Any]:
+    """Load JSON configuration."""
+    with open(path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def _load_toml(path: Path) -> Dict[str, Any]:
+    """Load TOML configuration."""
+    try:
+        import tomli
+    except ImportError:
+        try:
+            import tomllib as tomli  # Python 3.11+
+        except ImportError:
+            raise ImportError(
+                "TOML support requires 'tomli' package. "
+                "Install with: pip install tomli"
+            )
+    
+    with open(path, 'rb') as f:
+        return tomli.load(f)
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    """Load YAML configuration."""
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError(
+            "YAML support requires 'pyyaml' package. "
+            "Install with: pip install pyyaml"
+        )
+    
+    with open(path, 'r', encoding='utf-8') as f:
+        return yaml.safe_load(f)

mxx/runner/core/enums.py

@@ -0,0 +1,11 @@
+
+hook_types = [
+    "any_cond",
+    "all_cond",
+    "action",
+    "pre_action",
+    "post_action",
+    "on_true",
+    "on_false",
+    "on_error"
+]

mxx/runner/core/plugin.py

@@ -0,0 +1,23 @@
+
+from mxx.runner.core.callstack import PluginCallstackMeta
+from mxx.runner.core.enums import hook_types
+
+class MxxPlugin(metaclass=PluginCallstackMeta):
+    __cmdname__ : str = None
+
+def hook(hook_type : str):
+    def decorator(func):
+        if hook_type not in hook_types:
+            raise Exception(f"Invalid hook type: {hook_type}")
+
+        if hasattr(func, "_mxx_hook_types"):
+            raise Exception("Function is already registered as a hook")
+
+        # Mark the function with hook type
+        # Note: At class definition time, this is an unbound function
+        # The metaclass will bind it to the instance and register it
+        func._mxx_hook_types = hook_type
+        return func
+        
+    return decorator
+

mxx/runner/core/registry.py

@@ -0,0 +1,101 @@
+
+from pathlib import Path
+import importlib.util
+import sys
+import logging
+from mxx.runner.builtins.lifetime import Lifetime
+from mxx.runner.builtins.os_exec import OSExec
+from mxx.runner.builtins.app_launcher import AppLauncher
+from mxx.runner.builtins.mxxrun import MxxRun
+from mxx.runner.builtins.mxxset import MxxSet
+from mxx.runner.core.plugin import BasePlugin
+
+#home/.mxx/plugins
+PLUGIN_PATH = Path.home() / ".mxx" / "plugins"
+
+BUILTIN_MAPPINGS = {
+    "lifetime": Lifetime,
+    "os": OSExec,
+    "app": AppLauncher,
+    "mxxrun": MxxRun,
+    "mxxset": MxxSet,
+}
+
+# Start with builtins, will be extended with custom plugins from PLUGIN_PATH
+MAPPINGS = BUILTIN_MAPPINGS.copy()
+
+
+def _load_custom_plugins():
+    """
+    Load custom plugins from ~/.mxx/plugins/*.py
+    
+    Scans the plugins directory for Python files and loads classes
+    that inherit from BasePlugin.
+    """
+    if not PLUGIN_PATH.exists():
+        PLUGIN_PATH.mkdir(parents=True, exist_ok=True)
+        logging.info(f"Created plugin directory: {PLUGIN_PATH}")
+        return
+    
+    # Find all .py files in plugins directory
+    plugin_files = list(PLUGIN_PATH.glob("*.py"))
+    
+    if not plugin_files:
+        logging.debug(f"No custom plugins found in {PLUGIN_PATH}")
+        return
+    
+    loaded_count = 0
+    
+    for plugin_file in plugin_files:
+        # Skip __init__.py and private files
+        if plugin_file.name.startswith("_"):
+            continue
+        
+        try:
+            # Load the module dynamically
+            module_name = f"mxx.plugins.{plugin_file.stem}"
+            spec = importlib.util.spec_from_file_location(module_name, plugin_file)
+            
+            if spec is None or spec.loader is None:
+                logging.warning(f"Could not load spec for {plugin_file.name}")
+                continue
+            
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+            
+            # Find all BasePlugin subclasses in the module
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                
+                # Check if it's a class and inherits from BasePlugin
+                if (isinstance(attr, type) and 
+                    issubclass(attr, BasePlugin) and 
+                    attr is not BasePlugin):
+                    
+                    # Use the plugin's name attribute or class name
+                    plugin_name = getattr(attr, 'name', attr_name.lower())
+                    
+                    # Register the plugin
+                    MAPPINGS[plugin_name] = attr
+                    loaded_count += 1
+                    logging.info(f"Loaded custom plugin '{plugin_name}' from {plugin_file.name}")
+            
+        except Exception as e:
+            logging.error(f"Failed to load plugin from {plugin_file.name}: {e}", exc_info=True)
+    
+    if loaded_count > 0:
+        logging.info(f"Loaded {loaded_count} custom plugin(s) from {PLUGIN_PATH}")
+
+
+def initialize_registry():
+    """
+    Initialize the plugin registry by loading custom plugins.
+    
+    This should be called once at application startup.
+    """
+    _load_custom_plugins()
+
+
+# Auto-initialize on import
+initialize_registry()