mxx-tool 0.1.0__py3-none-any.whl

mxx/client/client.py

@@ -0,0 +1,316 @@
+"""
+MXX Scheduler Client
+
+Command-line interface for interacting with the MXX Scheduler Server.
+
+Usage:
+    mxx-client [OPTIONS] COMMAND [ARGS]...
+
+Commands:
+    list        List all jobs
+    status      Get status of a specific job
+    trigger     Trigger an on-demand job
+    cancel      Cancel a scheduled job
+    remove      Remove a completed/failed job
+    register    Register a new job
+    unregister  Unregister a job
+    registry    List registered jobs
+    health      Check server health
+"""
+
+import click
+import requests
+import json
+import os
+from pathlib import Path
+from typing import Optional
+import sys
+
+
+def get_server_url() -> str:
+    """Get server URL from environment or default"""
+    host = os.environ.get('MXX_SERVER_HOST', '127.0.0.1')
+    port = os.environ.get('MXX_SERVER_PORT', '5000')
+    return f"http://{host}:{port}"
+
+
+def handle_response(response: requests.Response, success_message: str = None):
+    """
+    Handle HTTP response and print formatted output.
+    
+    Args:
+        response: Response object
+        success_message: Optional message to show on success
+    """
+    try:
+        data = response.json()
+    except Exception:
+        data = {"text": response.text}
+    
+    if response.status_code >= 200 and response.status_code < 300:
+        if success_message:
+            click.echo(click.style(success_message, fg='green'))
+        
+        # Pretty print JSON data
+        if data:
+            click.echo(json.dumps(data, indent=2))
+    else:
+        click.echo(click.style(f"Error: {response.status_code}", fg='red'), err=True)
+        if 'error' in data:
+            click.echo(click.style(data['error'], fg='red'), err=True)
+            if 'hint' in data:
+                click.echo(click.style(f"Hint: {data['hint']}", fg='yellow'), err=True)
+        else:
+            click.echo(json.dumps(data, indent=2), err=True)
+        sys.exit(1)
+
+
+@click.group()
+@click.option('--server', default=None, help='Server URL (default: http://127.0.0.1:5000)')
+@click.pass_context
+def cli(ctx, server: Optional[str]):
+    """MXX Scheduler Client - Manage scheduled jobs"""
+    ctx.ensure_object(dict)
+    ctx.obj['SERVER_URL'] = server or get_server_url()
+
+
+@cli.command()
+@click.pass_context
+def health(ctx):
+    """Check server health"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.get(f"{server_url}/api/scheduler/health", timeout=5)
+        handle_response(response)
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.option('--type', 'filter_type', type=click.Choice(['all', 'active', 'scheduled']), 
+              default='all', help='Filter jobs by type')
+@click.pass_context
+def list(ctx, filter_type: str):
+    """List all jobs"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    if filter_type == 'active':
+        endpoint = f"{server_url}/api/scheduler/jobs/active"
+    else:
+        endpoint = f"{server_url}/api/scheduler/jobs"
+    
+    try:
+        response = requests.get(endpoint, timeout=5)
+        handle_response(response)
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def status(ctx, job_id: str):
+    """Get status of a specific job"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.get(f"{server_url}/api/scheduler/jobs/{job_id}", timeout=5)
+        handle_response(response)
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def trigger(ctx, job_id: str):
+    """Trigger an on-demand job to run immediately"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.post(f"{server_url}/api/scheduler/jobs/{job_id}/trigger", timeout=5)
+        handle_response(response, f"Job '{job_id}' triggered successfully")
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def cancel(ctx, job_id: str):
+    """Cancel a scheduled job"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.delete(f"{server_url}/api/scheduler/jobs/{job_id}", timeout=5)
+        handle_response(response, f"Job '{job_id}' cancelled successfully")
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def remove(ctx, job_id: str):
+    """Remove a completed/failed job from tracking"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.post(f"{server_url}/api/scheduler/jobs/{job_id}/remove", timeout=5)
+        handle_response(response, f"Job '{job_id}' removed successfully")
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('config_file', type=click.Path(exists=True))
+@click.option('--job-id', required=True, help='Unique identifier for the job')
+@click.option('--replace', is_flag=True, help='Replace existing job if it exists')
+@click.pass_context
+def register(ctx, config_file: str, job_id: str, replace: bool):
+    """
+    Register a new job from a configuration file.
+    
+    The config file should be in JSON, TOML, or YAML format.
+    It may include an optional [schedule] section.
+    
+    Example TOML:
+    \b
+        [lifetime]
+        lifetime = 3600
+        
+        [os]
+        cmd = "echo hello"
+        
+        [schedule]
+        trigger = "cron"
+        hour = 10
+        minute = 30
+    """
+    server_url = ctx.obj['SERVER_URL']
+    
+    # Load config file
+    config_path = Path(config_file)
+    
+    try:
+        from mxx.runner.core.config_loader import load_config
+        config_data = load_config(config_path)
+        
+        # Extract schedule if present
+        schedule_data = config_data.pop('schedule', None)
+        
+        # Prepare request payload
+        payload = {
+            'job_id': job_id,
+            'config': config_data,
+            'replace_existing': replace
+        }
+        
+        if schedule_data:
+            payload['schedule'] = schedule_data
+        
+        # Send request
+        response = requests.post(
+            f"{server_url}/api/scheduler/jobs",
+            json=payload,
+            timeout=10
+        )
+        
+        handle_response(response, f"Job '{job_id}' registered successfully")
+        
+    except ImportError:
+        click.echo(click.style("Error: mxx package not properly installed", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error loading config: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def unregister(ctx, job_id: str):
+    """Unregister a job from the registry"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.delete(f"{server_url}/api/scheduler/registry/{job_id}", timeout=5)
+        handle_response(response, f"Job '{job_id}' unregistered successfully")
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.option('--type', 'filter_type', 
+              type=click.Choice(['all', 'scheduled', 'on_demand']),
+              default='all', 
+              help='Filter by job type')
+@click.pass_context
+def registry(ctx, filter_type: str):
+    """List all registered jobs"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.get(
+            f"{server_url}/api/scheduler/registry",
+            params={'type': filter_type},
+            timeout=5
+        )
+        handle_response(response)
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument('job_id')
+@click.pass_context
+def info(ctx, job_id: str):
+    """Get detailed information about a registered job"""
+    server_url = ctx.obj['SERVER_URL']
+    
+    try:
+        response = requests.get(f"{server_url}/api/scheduler/registry/{job_id}", timeout=5)
+        handle_response(response)
+    except requests.exceptions.ConnectionError:
+        click.echo(click.style(f"Error: Cannot connect to server at {server_url}", fg='red'), err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(click.style(f"Error: {e}", fg='red'), err=True)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    cli()

mxx/runner/builtins/__init__.py

@@ -0,0 +1,18 @@
+"""
+Built-in plugins for the Mxx runner system.
+
+This module provides a collection of ready-to-use plugins for common tasks:
+- lifetime: Time-based execution control and process cleanup
+- os_exec: Execute arbitrary system commands
+- app_launcher: Launch external applications with Scoop integration
+"""
+
+from .lifetime import Lifetime
+from .os_exec import OSExec
+from .app_launcher import AppLauncher
+
+__all__ = [
+    "Lifetime",
+    "OSExec",
+    "AppLauncher",
+]

mxx/runner/builtins/app_launcher.py

@@ -0,0 +1,121 @@
+"""
+Application launcher plugin for launching external executables.
+
+This plugin manages external executable applications, supporting both
+Scoop-managed installations and custom paths.
+"""
+
+import os
+import subprocess
+from mxx.runner.core.plugin import MxxPlugin, hook
+
+
+class AppLauncher(MxxPlugin):
+    """
+    External executable launcher plugin.
+    
+    Launches and manages external executables with support for:
+    - Scoop package manager integration (automatic path resolution)
+    - Custom executable paths
+    - Automatic termination on shutdown
+    
+    Config Key: "app"
+    
+    The plugin resolves the executable path based on configuration,
+    verifies the file exists, launches it in detached mode, and
+    terminates it on shutdown.
+    
+    Example Configurations:
+        Scoop-managed:
+        ```toml
+        [app]
+        scoop = true
+        pkg = "my-app"
+        targetExe = "app.exe"
+        ```
+        
+        Custom path:
+        ```toml
+        [app]
+        scoop = false
+        path = "C:/MyApps/Tool"
+        targetExe = "tool.exe"
+        delay = 5
+        ```
+    """
+    
+    __cmdname__ = "app"
+
+    def __init__(self, scoop: bool = True, pkg: str = None, path: str = None, 
+                 targetExe: str = None, delay: int = 10, **kwargs):
+        super().__init__()
+        self.scoop = scoop
+        self.pkg = pkg
+        self.path = path
+        self.targetExe = targetExe
+        self.delay = delay
+        self.executable_path = None
+        
+        # Validation
+        if not self.targetExe:
+            raise ValueError("targetExe must be specified for App configuration.")
+        if self.scoop and not self.pkg:
+            raise ValueError("pkg must be specified when scoop is True for App configuration.")
+        if self.scoop and self.path:
+            raise ValueError("path should not be specified when scoop is True for App configuration.")
+
+    @hook("action")
+    def launch_application(self, runner):
+        """
+        Resolve executable path and launch the application.
+        
+        For Scoop installations, resolves path using SCOOP environment variable
+        or default location. For custom paths, uses the provided directory.
+        Verifies the executable exists before launching.
+        
+        Raises:
+            FileNotFoundError: If the executable file does not exist
+        """
+        if self.scoop:
+            scoop_path = os.environ.get("SCOOP", os.path.expanduser("~\\scoop"))
+            app_path = os.path.join(scoop_path, "apps", self.pkg, "current", self.targetExe)
+
+            if not os.path.isfile(app_path):
+                raise FileNotFoundError(f"App executable not found at {app_path}")
+            
+            self.executable_path = app_path
+        else:
+            app_path = os.path.join(self.path, self.targetExe)
+            if not os.path.isfile(app_path):
+                raise FileNotFoundError(f"App executable not found at {app_path}")
+            
+            self.executable_path = app_path
+
+        # Launch in detached mode
+        self._open_detached([self.executable_path])
+
+    @hook("post_action")
+    def shutdown_application(self, runner):
+        """
+        Forcefully terminate the launched executable.
+        
+        Uses Windows taskkill command to terminate the process by executable name.
+        """
+        os.system(f"taskkill /IM {self.targetExe} /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/lifetime.py

@@ -0,0 +1,114 @@
+"""
+Lifetime control plugin for time-based execution limits.
+
+This plugin manages the duration of runner execution and provides cleanup
+capabilities for processes, commands, and tasks at shutdown.
+"""
+
+import datetime
+import logging
+import os
+from mxx.runner.core.plugin import MxxPlugin, hook
+
+
+class Lifetime(MxxPlugin):
+    """
+    Time-based execution control plugin.
+    
+    Controls how long the runner executes and provides process cleanup at shutdown.
+    Other plugins can register items to kill on shutdown by adding to the killList.
+    
+    Config Key: "lifetime"
+    
+    Features:
+        - Sets execution duration in seconds
+        - Stops runner when time expires
+        - Kills registered processes/commands on shutdown
+        - Integrates with other plugins for cleanup coordination
+    
+    Example Configuration:
+        ```toml
+        [lifetime]
+        lifetime = 3600  # Run for 1 hour
+        ```
+    
+    Kill List Format:
+        Plugins can add items to self.killList as tuples:
+        - ("process", "process_name.exe") - Terminate by process name using psutil
+        - ("cmd", "command") - Terminate using taskkill /IM
+        - ("taskkill", "task_name") - Terminate using taskkill /IM
+    """
+    
+    __cmdname__ = "lifetime"
+
+    def __init__(self, lifetime: int = None, **kwargs):
+        super().__init__()
+        self.lifetime = lifetime
+        self.killList = []
+        self.targetStopTime = None
+
+    @hook("all_cond")
+    def can_run(self, runner):
+        """Check if lifetime is valid (greater than 0)."""
+        if self.lifetime is None:
+            return True
+        return self.lifetime > 0
+
+    @hook("action")
+    def calculate_stop_time(self, runner):
+        """Calculate and store the target stop time."""
+        if self.lifetime:
+            self.targetStopTime = datetime.datetime.now() + datetime.timedelta(seconds=self.lifetime)
+
+    @hook("on_true")
+    def should_continue(self, runner):
+        """Return True to continue, False to stop."""
+        if self.targetStopTime:
+            # Continue while time hasn't expired
+            return datetime.datetime.now() < self.targetStopTime
+        # No lifetime set, continue indefinitely
+        return True
+
+    @hook("post_action")
+    def cleanup(self, runner):
+        """
+        Terminate all registered processes, commands, and tasks.
+        
+        Iterates through killList and terminates items based on their type:
+        - process: Uses psutil to find and terminate by name
+        - cmd/taskkill: Uses Windows taskkill command
+        """
+        for killItem in self.killList:
+            match killItem:
+                case ("process", procName):
+                    logging.info(f"Terminating process: {procName}")
+                    try:
+                        import psutil
+                        killed = False
+                        for proc in psutil.process_iter(['name']):
+                            try:
+                                if proc.info['name'] == procName:
+                                    proc.kill()
+                                    proc.wait(timeout=5)
+                                    killed = True
+                                    logging.info(f"Successfully killed {procName}")
+                            except (psutil.NoSuchProcess, psutil.AccessDenied) as e:
+                                logging.warning(f"Could not kill process {procName}: {e}")
+                        
+                        if not killed:
+                            logging.warning(f"Process {procName} not found, trying taskkill")
+                            os.system(f"taskkill /IM {procName} /F")
+                    except Exception as e:
+                        logging.error(f"Failed to terminate process {procName}: {e}")
+                        # Fallback to taskkill
+                        os.system(f"taskkill /IM {procName} /F")
+                case ("cmd", cmdName):
+                    logging.info(f"Terminating command: {cmdName}")
+                    os.system(f"taskkill /IM {cmdName} /F")
+                case ("taskkill", taskName):
+                    logging.info(f"Terminating task: {taskName}")
+                    os.system(f"taskkill /IM {taskName} /F")
+                case _:
+                    pass
+
+        self.killList.clear()