Merge pull request #4 from jomardyan/codex/enhance-repository-functionality-5i0vev

Move sample script into examples and refresh docs

Author: jomardyan

README.md

@@ -158,6 +158,47 @@ print(f"Start Time: {result['metrics']['start_time']}")
 print(f"Exit Code: {result['exit_code']}")
 print(f"Success: {result['metrics']['success']}")
 ```
+
+## ⏱️ Task Scheduling & Automation
+
+Python Script Runner ships with a lightweight scheduler to automate recurring or event-driven jobs without standing up extra infrastructure. The scheduler includes:
+
+- **Automation & recurrence**: Define hourly, daily, weekly, or custom interval schedules (`every_5min`, `every_30min`) or supply a cron expression for more complex windows.
+- **Dependency-aware execution**: Chain tasks together so downstream jobs only start after upstream tasks complete successfully.
+- **Error handling & visibility**: Execution results are captured in-memory with status, error messages, and next-run timestamps for quick troubleshooting.
+- **Event triggers**: Bind tasks to custom events (for example, `on_script_failure`) and trigger them manually via the CLI.
+
+Basic usage:
+
+```python
+from runner import TaskScheduler
+
+scheduler = TaskScheduler()
+
+# Schedule a daily report and a dependent distribution step
+scheduler.add_scheduled_task("generate_report", "reports/daily.py", schedule="daily")
+scheduler.add_scheduled_task(
+    "distribute_report",
+    "reports/distribute.py",
+    dependencies=["generate_report"],
+)
+
+# Run any tasks that are due (e.g., inside a cron shell)
+for result in scheduler.run_due_tasks():
+    print(result)
+```
+
+You can also interact via the CLI:
+
+```bash
+python -m runner \
+  --add-scheduled-task nightly_cleanup \
+  --script scripts/cleanup.py \
+  --schedule daily \
+  --list-scheduled-tasks
+```
+
+The scheduler respects dependency ordering automatically; if a prerequisite task fails, dependent tasks are skipped until the next eligible run.
 **Benefit**: SQLite database provides immutable audit trail for SOC2/HIPAA compliance. Every execution logged with full context.
 
 ---
@@ -186,6 +227,8 @@ python -m runner script.py --slack-webhook "YOUR_WEBHOOK_URL"
 python-script-runner myscript.py
 ```
 
+> Need a quick smoke test? Run the bundled sample script with `python -m runner examples/sample_script.py` to see the default metrics output without creating your own file first.
+
 ### 📊 Default Output - Comprehensive Metrics Report
 
 Every run automatically displays a detailed metrics report with:

dashboard/backend/test_app.py

@@ -57,7 +57,7 @@ def test_database():
     cursor.execute("""INSERT INTO executions 
         (script_path, script_args, start_time, end_time, execution_time_seconds, exit_code, success, stdout_lines, stderr_lines, created_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""", 
-        ('test_script.py', '', now, now, 1.5, 0, True, 10, 0, now))
+        ('sample_script.py', '', now, now, 1.5, 0, True, 10, 0, now))
     exec_id = cursor.lastrowid
 
     cursor.execute("""INSERT INTO metrics (execution_id, metric_name, metric_value)

docs/installation.md

@@ -57,7 +57,7 @@ docker run --rm psr myscript.py
 ```bash
 python runner.py --version
 python runner.py --help
-python runner.py test_script.py
+python runner.py examples/sample_script.py
 ```
 
 ## Troubleshooting

examples/sample_script.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+"""Simple sample script for Python Script Runner demonstration."""
+
+print("Python Script Runner - Sample Script")
+print("✅ Sample completed successfully")

release.sh

@@ -728,7 +728,7 @@ cmd_validate() {
     # Check Python compilation
     print_step "Checking code quality..."
     local compile_output
-    if compile_output=$(python3 -m py_compile runner.py test_script.py 2>&1); then
+    if compile_output=$(python3 -m py_compile runner.py examples/sample_script.py 2>&1); then
         print_success "Compilation successful"
     else
         print_error "Python compilation failed:"

runner.py

@@ -2888,64 +2888,96 @@ def get_optimization_report(self, script_path: str, days: int = 30) -> str:
 
 class ScheduledTask:
     """Represents a scheduled task"""
-    
+
     def __init__(self, task_id: str, script_path: str, schedule: Optional[str] = None,
                  cron_expr: Optional[str] = None, trigger_events: Optional[List[str]] = None,
-                 enabled: bool = True):
+                 enabled: bool = True, script_args: Optional[List[str]] = None,
+                 dependencies: Optional[List[str]] = None):
         """Initialize scheduled task
-        
+
         Args:
             task_id: Unique task identifier
             script_path: Path to script to execute
             schedule: Simple schedule (e.g., 'daily', 'hourly', 'every_5min')
             cron_expr: Cron expression for complex schedules
             trigger_events: Event names that trigger execution
             enabled: Whether task is enabled
+            script_args: Arguments to pass to the script during execution
+            dependencies: Other task IDs that must complete successfully first
         """
         self.task_id = task_id
         self.script_path = script_path
         self.schedule = schedule
         self.cron_expr = cron_expr
         self.trigger_events = trigger_events or []
         self.enabled = enabled
+        self.script_args = script_args or []
+        self.dependencies = dependencies or []
         self.last_run: Optional[datetime] = None
         self.next_run: Optional[datetime] = None
         self.run_count = 0
-        self.last_status = None
+        self.last_status: Optional[str] = None
+        self.last_error: Optional[str] = None
 
 
 class TaskScheduler:
     """Manages scheduled script execution and event-driven triggers"""
-    
-    def __init__(self, logger: Optional[logging.Logger] = None):
+
+    def __init__(self, logger: Optional[logging.Logger] = None, history_db: Optional[str] = None):
         """Initialize scheduler
-        
+
         Args:
             logger: Logger instance
+            history_db: Optional history database path passed to ScriptRunner
         """
         self.logger = logger or logging.getLogger(__name__)
         self.tasks = {}
         self.events = {}
-        self.triggered_tasks = []
-    
+        self.triggered_tasks: List[str] = []
+        self.history_db = history_db
+        self.execution_log: List[Dict[str, Any]] = []
+
     def add_scheduled_task(self, task_id: str, script_path: str,
-                          schedule: Optional[str] = None, cron_expr: Optional[str] = None) -> ScheduledTask:
+                          schedule: Optional[str] = None, cron_expr: Optional[str] = None,
+                          script_args: Optional[List[str]] = None,
+                          dependencies: Optional[List[str]] = None) -> ScheduledTask:
         """Add a scheduled task
-        
+
         Args:
             task_id: Unique identifier
             script_path: Script to run
             schedule: Simple schedule string
             cron_expr: Cron expression
-            
+            script_args: Arguments for the script
+            dependencies: List of prerequisite task IDs
+
         Returns:
             ScheduledTask object
         """
-        task = ScheduledTask(task_id, script_path, schedule, cron_expr)
+        task = ScheduledTask(task_id, script_path, schedule, cron_expr, script_args=script_args,
+                             dependencies=dependencies)
         self.tasks[task_id] = task
         self._calculate_next_run(task)
         self.logger.info(f"Added task '{task_id}': {script_path}")
         return task
+
+    def add_dependencies(self, task_id: str, dependencies: List[str]) -> bool:
+        """Register dependencies for an existing task.
+
+        Args:
+            task_id: Task that should wait on dependencies
+            dependencies: Other task IDs that must complete successfully
+
+        Returns:
+            bool: True if dependencies were added
+        """
+        if task_id not in self.tasks:
+            self.logger.error(f"Task '{task_id}' not found")
+            return False
+
+        self.tasks[task_id].dependencies = list(dependencies)
+        self.logger.info(f"Task '{task_id}' dependencies set: {', '.join(dependencies)}")
+        return True
 
     def add_event_trigger(self, task_id: str, event_name: str) -> bool:
         """Add event trigger for a task
@@ -2982,7 +3014,15 @@ def trigger_event(self, event_name: str) -> List[str]:
         tasks = self.events.get(event_name, [])
         self.logger.info(f"Event '{event_name}' triggered: {len(tasks)} tasks")
         return tasks
-    
+
+    def _dependencies_satisfied(self, task: ScheduledTask) -> bool:
+        """Check whether all dependencies for a task are successful."""
+        for dep_id in task.dependencies:
+            dep = self.tasks.get(dep_id)
+            if not dep or dep.last_status != "success":
+                return False
+        return True
+
     def get_due_tasks(self) -> List[ScheduledTask]:
         """Get tasks that are due for execution
         
@@ -3015,6 +3055,89 @@ def mark_executed(self, task_id: str, status: str = "success"):
             task.run_count += 1
             self._calculate_next_run(task)
             self.logger.info(f"Task '{task_id}' executed: {status}")
+
+    def run_task(self, task_id: str, runner_factory: Optional[Callable[..., Any]] = None,
+                 runner_kwargs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Execute a task immediately using the provided runner factory."""
+        if task_id not in self.tasks:
+            raise ValueError(f"Task '{task_id}' not found")
+
+        task = self.tasks[task_id]
+        runner_kwargs = runner_kwargs or {}
+        runner_factory = runner_factory or ScriptRunner
+
+        if not self._dependencies_satisfied(task):
+            self.logger.info(f"Task '{task_id}' skipped: waiting on dependencies")
+            return {"task_id": task_id, "status": "skipped", "reason": "dependencies_pending"}
+
+        try:
+            runner = runner_factory(
+                task.script_path,
+                script_args=task.script_args,
+                history_db=self.history_db,
+                **runner_kwargs,
+            )
+            execution = runner.run_script()
+            status = "success" if execution.get("returncode") == 0 else "failed"
+            error = execution.get("stderr") if status == "failed" else None
+        except Exception as exc:
+            execution = None
+            status = "failed"
+            error = str(exc)
+
+        task.last_error = error
+        self.mark_executed(task_id, status)
+
+        log_entry = {
+            "task_id": task_id,
+            "status": status,
+            "timestamp": datetime.now().isoformat(),
+            "error": error,
+            "next_run": task.next_run.isoformat() if task.next_run else None,
+        }
+        self.execution_log.append(log_entry)
+
+        if status != "success":
+            self.logger.error(f"Task '{task_id}' failed: {error}")
+        else:
+            self.logger.info(f"Task '{task_id}' completed successfully")
+
+        return {
+            "task_id": task_id,
+            "status": status,
+            "error": error,
+            "metrics": execution.get("metrics") if execution else None,
+        }
+
+    def run_due_tasks(self, runner_factory: Optional[Callable[..., Any]] = None,
+                      runner_kwargs: Optional[Dict[str, Any]] = None,
+                      stop_on_error: bool = False) -> List[Dict[str, Any]]:
+        """Execute all due tasks whose dependencies are satisfied."""
+        results: List[Dict[str, Any]] = []
+        pending = {task.task_id: task for task in self.get_due_tasks()}
+
+        runner_factory = runner_factory or ScriptRunner
+        runner_kwargs = runner_kwargs or {}
+
+        while pending:
+            progressed = False
+            for task_id, task in list(pending.items()):
+                if not self._dependencies_satisfied(task):
+                    continue
+
+                result = self.run_task(task_id, runner_factory=runner_factory, runner_kwargs=runner_kwargs)
+                results.append(result)
+                progressed = True
+                pending.pop(task_id, None)
+
+                if stop_on_error and result.get("status") != "success":
+                    return results
+
+            if not progressed:
+                self.logger.info("No further progress possible; remaining tasks waiting on dependencies")
+                break
+
+        return results
 
     def _calculate_next_run(self, task: ScheduledTask):
         """Calculate next run time for task
@@ -3045,6 +3168,14 @@ def _calculate_next_run(self, task: ScheduledTask):
                         task.next_run = now + timedelta(seconds=amount)
             except Exception as e:
                 self.logger.error(f"Error parsing schedule '{task.schedule}': {e}")
+        elif task.cron_expr:
+            try:
+                from croniter import croniter  # type: ignore
+
+                iterator = croniter(task.cron_expr, now)
+                task.next_run = iterator.get_next(datetime)
+            except Exception as e:
+                self.logger.error(f"Error parsing cron expression '{task.cron_expr}': {e}")
         else:
             task.next_run = now + timedelta(hours=1)  # Default to 1 hour
 
@@ -3069,7 +3200,9 @@ def get_task_status(self, task_id: str) -> Dict:
             "next_run": task.next_run.isoformat() if task.next_run else None,
             "run_count": task.run_count,
             "last_status": task.last_status,
-            "triggers": task.trigger_events
+            "triggers": task.trigger_events,
+            "dependencies": task.dependencies,
+            "last_error": task.last_error,
         }
 
     def list_tasks(self) -> List[Dict]:
@@ -7853,6 +7986,8 @@ def main():
                         print(f"   Enabled: {task['enabled']}")
                         print(f"   Runs: {task['run_count']}")
                         print(f"   Last status: {task['last_status']}")
+                        if task.get('dependencies'):
+                            print(f"   Depends on: {', '.join(task['dependencies'])}")
                         if task['triggers']:
                             print(f"   Triggers: {', '.join(task['triggers'])}")
                 else:

setup.ps1

@@ -425,14 +425,14 @@ catch {
 if ($SETUP_COMMAND -eq "develop") {
     Write-Section "✓ Development installation completed!"
     Write-Host "You can now run the script runner:"
-    Write-Host "  python-script-runner test_script.py"
-    Write-Host "  python -m runner test_script.py"
+    Write-Host "  python-script-runner examples/sample_script.py"
+    Write-Host "  python -m runner examples/sample_script.py"
     Write-Host ""
 }
 elseif ($SETUP_COMMAND -eq "install") {
     Write-Section "✓ Installation completed!"
     Write-Host "You can now run the script runner:"
-    Write-Host "  python-script-runner test_script.py"
+    Write-Host "  python-script-runner examples/sample_script.py"
     Write-Host ""
 }
 elseif ($SETUP_COMMAND -eq "py2exe") {
@@ -442,7 +442,7 @@ elseif ($SETUP_COMMAND -eq "py2exe") {
         Write-Host "  dist\python-script-runner.exe"
         Write-Host ""
         Write-Host "To test the executable, run:"
-        Write-Host "  .\dist\python-script-runner.exe test_script.py"
+        Write-Host "  .\dist\python-script-runner.exe examples/sample_script.py"
         Write-Host ""
         Write-Host "You can distribute this executable to other Windows machines"
         Write-Host "without requiring Python installation."
@@ -472,8 +472,8 @@ Write-Success "Virtual environment is ACTIVE"
 Write-Host ""
 Write-Host "The virtual environment will remain active in this PowerShell session."
 Write-Host "You can now run commands like:"
-Write-Host "  python-script-runner test_script.py"
-Write-Host "  python -m runner test_script.py"
+Write-Host "  python-script-runner examples/sample_script.py"
+Write-Host "  python -m runner examples/sample_script.py"
 Write-Host ""
 Write-Host "To deactivate the virtual environment, type: deactivate"
 Write-Host ""