feat: Add system health monitoring module (#128)

cortex/cli.py

@@ -1,15 +1,20 @@
 import argparse
 import logging
 import os
 import sys
 import time
 from datetime import datetime
 from typing import Any
 
 from cortex.branding import VERSION, console, cx_header, cx_print, show_banner
 from cortex.coordinator import InstallationCoordinator, StepStatus
+from cortex.installation_history import (
+    InstallationHistory,
+    InstallationStatus,
+    InstallationType,
+)
 from cortex.demo import run_demo
 from cortex.installation_history import InstallationHistory, InstallationStatus, InstallationType
 from cortex.llm.interpreter import CommandInterpreter
 from cortex.notification_manager import NotificationManager
 from cortex.stack_manager import StackManager
@@ -101,10 +106,9 @@
         sys.stdout.write("\r\033[K")
         sys.stdout.flush()
 
-    # --- New Notification Method ---
+    # --- Notification Method ---
     def notify(self, args):
         """Handle notification commands"""
-        # Addressing CodeRabbit feedback: Handle missing subcommand gracefully
         if not args.notify_action:
             self._print_error("Please specify a subcommand (config/enable/disable/dnd/send)")
             return 1
@@ -127,24 +131,22 @@
 
         elif args.notify_action == "enable":
             mgr.config["enabled"] = True
-            # Addressing CodeRabbit feedback: Ideally should use a public method instead of private _save_config,
-            # but keeping as is for a simple fix (or adding a save method to NotificationManager would be best).
-            mgr._save_config()
+            mgr.save_config()
             self._print_success("Notifications enabled")
             return 0
 
         elif args.notify_action == "disable":
             mgr.config["enabled"] = False
-            mgr._save_config()
-            cx_print("Notifications disabled (Critical alerts will still show)", "warning")
+            mgr.save_config()
+            self._print_success("Notifications disabled (Critical alerts will still show)")
             return 0
 
         elif args.notify_action == "dnd":
             if not args.start or not args.end:
                 self._print_error("Please provide start and end times (HH:MM)")
                 return 1
 
-            # Addressing CodeRabbit feedback: Add time format validation
+            # Add time format validation
             try:
                 datetime.strptime(args.start, "%H:%M")
                 datetime.strptime(args.end, "%H:%M")
@@ -154,7 +156,7 @@
 
             mgr.config["dnd_start"] = args.start
             mgr.config["dnd_end"] = args.end
-            mgr._save_config()
+            mgr.save_config()
             self._print_success(f"DND Window updated: {args.start} - {args.end}")
             return 0
 
@@ -170,6 +172,76 @@
             self._print_error("Unknown notify command")
             return 1
 
+    # --- Health Command ---
+    def health(self, args):
+        """Run system health checks and show recommendations.
+
+        Args:
+            args: Parsed command line arguments.
+
+        Returns:
+            int: 0 on success, 1 on failure.
+        """
+        try:
+            from cortex.health.monitor import HealthMonitor
+
+            self._print_status("🔍", "Running system health checks...")
+            monitor = HealthMonitor()
+            report = monitor.run_all()
+
+            # --- Display Results ---
+            score = report["total_score"]
+
+            # Color code the score
+            score_color = "green"
+            if score < 60:
+                score_color = "red"
+            elif score < 80:
+                score_color = "yellow"
+
+            console.print()
+            console.print(
+                f"📊 [bold]System Health Score:[/bold] [{score_color}]{score}/100[/{score_color}]"
+            )
+            console.print()
+
+            console.print("[bold]Factors:[/bold]")
+            recommendations = []
+
+            for res in report["results"]:
+                status_icon = "✅"
+                if res["status"] == "WARNING":
+                    status_icon = "⚠️ "
+                elif res["status"] == "CRITICAL":
+                    status_icon = "❌"
+
+                console.print(
+                    f"   {status_icon}  {res['name']:<15}: {res['score']}/100 ({res['details']})"
+                )
+
+                if res["recommendation"]:
+                    recommendations.append(res["recommendation"])
+
+            console.print()
+
+            if recommendations:
+                console.print("[bold]Recommendations:[/bold]")
+                for i, rec in enumerate(recommendations, 1):
+                    console.print(f"   {i}. {rec}")
+
+                console.print()
+                console.print("[dim]Run suggested commands manually to improve your score.[/dim]")
+            else:
+                self._print_success("System is in excellent health! No actions needed.")
+
+            return 0
+        except ImportError as e:
+            self._print_error(f"Health module not available: {e}")
+            return 1
+        except Exception as e:
+            self._print_error(f"Health check failed: {e}")
+            return 1
+
     # -------------------------------
     def demo(self):
         """
@@ -462,7 +534,7 @@
 
                 coordinator = InstallationCoordinator(
                     commands=commands,
-                    descriptions=[f"Step {i+1}" for i in range(len(commands))],
+                    descriptions=[f"Step {i + 1}" for i in range(len(commands))],
                     timeout=300,
                     stop_on_error=True,
                     progress_callback=progress_callback,
@@ -591,7 +663,7 @@
                     date = r.timestamp[:19].replace("T", " ")
                     packages = ", ".join(r.packages[:2])
                     if len(r.packages) > 2:
-                        packages += f" +{len(r.packages)-2}"
+                        packages += f" +{len(r.packages) - 2}"
 
                     print(
                         f"{r.id:<18} {date:<20} {r.operation_type.value:<12} {packages:<30} {r.status.value:<15}"
@@ -767,9 +839,10 @@
     table.add_row("install <pkg>", "Install software")
     table.add_row("history", "View history")
     table.add_row("rollback <id>", "Undo installation")
-    table.add_row("notify", "Manage desktop notifications")  # Added this line
+    table.add_row("notify", "Manage desktop notifications")
     table.add_row("cache stats", "Show LLM cache statistics")
     table.add_row("stack <name>", "Install the stack")
+    table.add_row("health", "Check system health score")
     table.add_row("doctor", "System health check")
 
     console.print(table)
@@ -858,7 +931,7 @@
     edit_pref_parser.add_argument("key", nargs="?")
     edit_pref_parser.add_argument("value", nargs="?")
 
-    # --- New Notify Command ---
+    # --- Notify Command ---
     notify_parser = subparsers.add_parser("notify", help="Manage desktop notifications")
     notify_subs = notify_parser.add_subparsers(dest="notify_action", help="Notify actions")
 
@@ -875,6 +948,9 @@
     send_parser.add_argument("--title", default="Cortex Notification")
     send_parser.add_argument("--level", choices=["low", "normal", "critical"], default="normal")
     send_parser.add_argument("--actions", nargs="*", help="Action buttons")
+
+    # --- Health Command ---
+    subparsers.add_parser("health", help="Check system health score")
     # --------------------------
 
     # Stack command
@@ -924,9 +1000,10 @@
             return cli.check_pref(key=args.key)
         elif args.command == "edit-pref":
             return cli.edit_pref(action=args.action, key=args.key, value=args.value)
-        # Handle the new notify command
         elif args.command == "notify":
             return cli.notify(args)
+        elif args.command == "health":
+            return cli.health(args)
         elif args.command == "stack":
             return cli.stack(args)
         elif args.command == "doctor":

cortex/health/checks/disk.py

@@ -0,0 +1,61 @@
+import shutil
+
+from ..monitor import CheckResult, HealthCheck
+
+
+class DiskCheck(HealthCheck):
+    """Check root filesystem disk usage."""
+
+    def run(self) -> CheckResult:
+        """Calculate disk usage percentage.
+
+        Returns:
+            CheckResult based on usage thresholds.
+        """
+        try:
+            # Use _ for unused variable (free space)
+            total, used, _ = shutil.disk_usage("/")
+            usage_percent = (used / total) * 100
+        except Exception as e:
+            return CheckResult(
+                name="Disk Usage",
+                category="disk",
+                score=0,
+                status="CRITICAL",
+                details=f"Check failed: {e}",
+                recommendation="Check disk mounts and permissions",
+                weight=0.20,
+            )
+
+        # Explicit early returns to avoid static analysis confusion
+        if usage_percent > 90:
+            return CheckResult(
+                name="Disk Usage",
+                category="disk",
+                score=0,
+                status="CRITICAL",
+                details=f"{usage_percent:.1f}% used",
+                recommendation="Clean up disk space immediately",
+                weight=0.20,
+            )
+
+        if usage_percent > 80:
+            return CheckResult(
+                name="Disk Usage",
+                category="disk",
+                score=50,
+                status="WARNING",
+                details=f"{usage_percent:.1f}% used",
+                recommendation="Consider cleaning up disk space",
+                weight=0.20,
+            )
+
+        return CheckResult(
+            name="Disk Usage",
+            category="disk",
+            score=100,
+            status="OK",
+            details=f"{usage_percent:.1f}% used",
+            recommendation=None,
+            weight=0.20,
+        )

cortex/health/checks/performance.py

@@ -0,0 +1,72 @@
+import multiprocessing
+import os
+
+from ..monitor import CheckResult, HealthCheck
+
+
+class PerformanceCheck(HealthCheck):
+    """Check system performance metrics including CPU load and memory usage."""
+
+    def run(self) -> CheckResult:
+        """Check system load and memory usage.
+
+        Returns:
+            CheckResult with performance score.
+        """
+        score = 100
+        issues = []
+        rec = None
+
+        # 1. Load Average (1min)
+        try:
+            load1, _, _ = os.getloadavg()
+            cores = multiprocessing.cpu_count()
+            # Load ratio against core count
+            load_ratio = load1 / cores
+
+            if load_ratio > 1.0:
+                score -= 50
+                issues.append(f"High Load ({load1:.2f})")
+                rec = "Check top processes"
+        except OSError:
+            pass  # Skip on Windows etc.
+
+        # 2. Memory Usage (Linux /proc/meminfo)
+        try:
+            with open("/proc/meminfo") as f:
+                meminfo = {}
+                for line in f:
+                    parts = line.split(":")
+                    if len(parts) == 2:
+                        meminfo[parts[0].strip()] = int(parts[1].strip().split()[0])
+
+                if "MemTotal" in meminfo and "MemAvailable" in meminfo:
+                    total = meminfo["MemTotal"]
+                    avail = meminfo["MemAvailable"]
+                    used_percent = ((total - avail) / total) * 100
+
+                    if used_percent > 80:
+                        penalty = int(used_percent - 80)
+                        score -= penalty
+                        issues.append(f"High Memory ({used_percent:.0f}%)")
+        except FileNotFoundError:
+            pass  # Non-Linux systems
+
+        # Summary of results
+        status = "OK"
+        if score < 50:
+            status = "CRITICAL"
+        elif score < 90:
+            status = "WARNING"
+
+        details = ", ".join(issues) if issues else "Optimal"
+
+        return CheckResult(
+            name="System Load",
+            category="performance",
+            score=max(0, score),
+            status=status,
+            details=details,
+            recommendation=rec,
+            weight=0.20,  # 20%
+        )