process-watchdog 1.0.0

package/src/platform/windows.ts

@@ -0,0 +1,242 @@
+import { execFileSync } from 'node:child_process';
+import type {
+  PlatformAdapter,
+  ProcessInfo,
+  MemoryInfo,
+  DiskInfo,
+  CpuSample,
+  StartupItem,
+} from './platform.interface.js';
+
+function ps(script: string): string {
+  return execFileSync(
+    'powershell.exe',
+    ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
+    {
+      encoding: 'utf-8',
+      timeout: 60000,
+    },
+  ).trim();
+}
+
+function psJson<T>(script: string): T {
+  const raw = ps(`${script} | ConvertTo-Json -Compress`);
+  if (!raw) return [] as unknown as T;
+  return JSON.parse(raw) as T;
+}
+
+export class WindowsPlatform implements PlatformAdapter {
+  async getProcesses(): Promise<ProcessInfo[]> {
+    type RawProcess = {
+      Id: number;
+      ProcessName: string;
+      memoryMB: number;
+      cpu: number | null;
+      Responding: boolean;
+    };
+
+    const result = psJson<RawProcess | RawProcess[]>(
+      `Get-Process -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, @{N='memoryMB';E={[math]::Round($_.WorkingSet64/1MB)}}, @{N='cpu';E={$_.CPU}}, Responding`,
+    );
+    const arr = Array.isArray(result) ? result : [result];
+    return arr.map((p) => ({
+      pid: p.Id,
+      name: p.ProcessName,
+      memoryMB: p.memoryMB ?? 0,
+      cpu: p.cpu ?? 0,
+      responding: p.Responding ?? false,
+    }));
+  }
+
+  async getProcessesByName(name: string): Promise<ProcessInfo[]> {
+    type RawProcess = {
+      Id: number;
+      ProcessName: string;
+      memoryMB: number;
+      cpu: number | null;
+      Responding: boolean;
+    };
+
+    const result = psJson<RawProcess | RawProcess[]>(
+      `Get-Process ${name} -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, @{N='memoryMB';E={[math]::Round($_.WorkingSet64/1MB)}}, @{N='cpu';E={$_.CPU}}, Responding`,
+    );
+    const arr = Array.isArray(result) ? result : [result];
+    return arr.map((p) => ({
+      pid: p.Id,
+      name: p.ProcessName,
+      memoryMB: p.memoryMB ?? 0,
+      cpu: p.cpu ?? 0,
+      responding: p.Responding ?? false,
+    }));
+  }
+
+  async getListeningPids(): Promise<number[]> {
+    type RawConn = { OwningProcess: number };
+    const result = psJson<RawConn | RawConn[]>(
+      `Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue | Select-Object OwningProcess -Unique`,
+    );
+    if (!result) return [];
+    const arr = Array.isArray(result) ? result : [result];
+    return arr.map((c) => c.OwningProcess);
+  }
+
+  async killProcess(pid: number): Promise<boolean> {
+    try {
+      ps(`Stop-Process -Id ${pid} -Force -ErrorAction Stop`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async getMemoryInfo(): Promise<MemoryInfo> {
+    type RawOS = { TotalVisibleMemorySize: number; FreePhysicalMemory: number };
+    type RawPageFile = { CurrentUsage: number };
+
+    const osInfo = psJson<RawOS | RawOS[]>(
+      `Get-CimInstance Win32_OperatingSystem | Select-Object TotalVisibleMemorySize, FreePhysicalMemory`,
+    );
+    const osArr = Array.isArray(osInfo) ? osInfo : [osInfo];
+    const os = osArr[0];
+
+    const totalMB = Math.round(os.TotalVisibleMemorySize / 1024);
+    const freeMB = Math.round(os.FreePhysicalMemory / 1024);
+    const usedMB = totalMB - freeMB;
+    const usedPct = totalMB > 0 ? Math.round((usedMB / totalMB) * 100) : 0;
+
+    let pageFileUsageMB = 0;
+    try {
+      const pfInfo = psJson<RawPageFile | RawPageFile[]>(
+        `Get-CimInstance Win32_PageFileUsage | Select-Object CurrentUsage`,
+      );
+      if (pfInfo) {
+        const pfArr = Array.isArray(pfInfo) ? pfInfo : [pfInfo];
+        pageFileUsageMB = pfArr.reduce((sum, pf) => sum + (pf.CurrentUsage ?? 0), 0);
+      }
+    } catch {
+      // page file info is optional
+    }
+
+    return { totalMB, freeMB, usedPct, pageFileUsageMB };
+  }
+
+  async getDiskInfo(): Promise<DiskInfo[]> {
+    type RawDisk = { DeviceID: string; totalGB: number; freeGB: number };
+
+    const result = psJson<RawDisk | RawDisk[]>(
+      `Get-CimInstance Win32_LogicalDisk -Filter "DriveType=3" | Select-Object DeviceID, @{N='totalGB';E={[math]::Round($_.Size/1GB)}}, @{N='freeGB';E={[math]::Round($_.FreeSpace/1GB)}}`,
+    );
+    const arr = Array.isArray(result) ? result : [result];
+    return arr.map((d) => {
+      const usedGB = d.totalGB - d.freeGB;
+      const usedPct = d.totalGB > 0 ? Math.round((usedGB / d.totalGB) * 100) : 0;
+      return {
+        drive: d.DeviceID,
+        totalGB: d.totalGB,
+        freeGB: d.freeGB,
+        usedPct,
+      };
+    });
+  }
+
+  async getCpuUsage(samples: number, intervalMs: number): Promise<CpuSample[]> {
+    const intervalSec = Math.max(1, Math.round(intervalMs / 1000));
+
+    type RawCounter = {
+      Readings: string;
+      Timestamp: string;
+    };
+
+    type RawCounterSet = {
+      CounterSamples: Array<{ CookedValue: number; Timestamp: string }>;
+    };
+
+    try {
+      const raw = ps(
+        `$c = Get-Counter '\\Processor(_Total)\\% Processor Time' -SampleInterval ${intervalSec} -MaxSamples ${samples}; $c.CounterSamples | Select-Object CookedValue, Timestamp | ConvertTo-Json -Compress`,
+      );
+      if (!raw) return [];
+      const parsed = JSON.parse(raw) as
+        | { CookedValue: number; Timestamp: string }
+        | { CookedValue: number; Timestamp: string }[];
+      const arr = Array.isArray(parsed) ? parsed : [parsed];
+      return arr.map((s) => ({
+        usedPct: Math.round(s.CookedValue),
+        timestamp: new Date(s.Timestamp),
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  async getStartupItems(): Promise<StartupItem[]> {
+    const items: StartupItem[] = [];
+
+    // Read from registry run key
+    try {
+      const raw = ps(
+        `$reg = 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run'; if (Test-Path $reg) { Get-ItemProperty $reg | Select-Object * -ExcludeProperty PSPath,PSParentPath,PSChildName,PSDrive,PSProvider | ConvertTo-Json -Compress }`,
+      );
+      if (raw) {
+        const obj = JSON.parse(raw) as Record<string, string>;
+        for (const [name, command] of Object.entries(obj)) {
+          items.push({
+            name,
+            command,
+            location: 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run',
+            enabled: true,
+          });
+        }
+      }
+    } catch {
+      // registry read failed, continue
+    }
+
+    // Read from startup folder
+    try {
+      const startupFolder = ps(
+        `[Environment]::GetFolderPath('Startup')`,
+      );
+      if (startupFolder) {
+        const files = ps(
+          `$f = [Environment]::GetFolderPath('Startup'); if (Test-Path $f) { Get-ChildItem $f -File | Select-Object Name, FullName | ConvertTo-Json -Compress }`,
+        );
+        if (files) {
+          const parsed = JSON.parse(files) as
+            | { Name: string; FullName: string }
+            | { Name: string; FullName: string }[];
+          const arr = Array.isArray(parsed) ? parsed : [parsed];
+          for (const f of arr) {
+            items.push({
+              name: f.Name,
+              command: f.FullName,
+              location: startupFolder,
+              enabled: true,
+            });
+          }
+        }
+      }
+    } catch {
+      // startup folder read failed, continue
+    }
+
+    return items;
+  }
+
+  async disableStartupItem(name: string): Promise<boolean> {
+    try {
+      ps(
+        `Remove-ItemProperty -Path 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' -Name '${name}' -ErrorAction Stop`,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  getTempDirs(): string[] {
+    return [process.env.TEMP, process.env.APPDATA ? process.env.APPDATA + '\\npm-cache' : undefined].filter(
+      (d): d is string => Boolean(d),
+    );
+  }
+}

package/src/plugins/cpu-monitor.ts

@@ -0,0 +1,67 @@
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from './plugin.interface.js';
+import { getPlatform } from '../platform/index.js';
+
+export class CpuMonitorPlugin implements WatchdogPlugin {
+  name = 'cpu-monitor';
+  description = 'Detect sustained high CPU usage and identify culprits';
+  defaultInterval = 120000;
+  private config: PluginConfig = {
+    enabled: true,
+    interval: 120000,
+    autoFix: false,
+    thresholds: { warningPct: 75, criticalPct: 90 },
+  };
+
+  configure(opts: PluginConfig): void {
+    this.config = { ...this.config, ...opts };
+  }
+
+  async check(): Promise<HealthCheck> {
+    const platform = getPlatform();
+    const samples = await platform.getCpuUsage(3, 2000);
+
+    const sampleCount = samples.length;
+    const cpuUsedPct =
+      sampleCount > 0
+        ? samples.reduce((sum, s) => sum + s.usedPct, 0) / sampleCount
+        : 0;
+
+    const warningPct = this.config.thresholds['warningPct'] ?? 75;
+    const criticalPct = this.config.thresholds['criticalPct'] ?? 90;
+
+    let status: HealthCheck['status'];
+    const suggestedActions: string[] = [];
+
+    if (cpuUsedPct >= criticalPct) {
+      status = 'critical';
+      suggestedActions.push('CPU critically high — investigate top CPU-consuming processes');
+    } else if (cpuUsedPct >= warningPct) {
+      status = 'warning';
+      suggestedActions.push('CPU usage elevated — monitor for sustained spikes');
+    } else {
+      status = 'healthy';
+    }
+
+    const message = `Average CPU usage: ${cpuUsedPct.toFixed(1)}% over ${sampleCount} sample(s)`;
+
+    return {
+      status,
+      metrics: { cpuUsedPct, sampleCount },
+      message,
+      suggestedActions,
+    };
+  }
+
+  async fix(): Promise<FixResult> {
+    // Alert-only: no automated process killing for CPU
+    const check = await this.check();
+    const metrics = check.metrics;
+
+    return {
+      actionsKept: ['CPU monitor is alert-only; no automated fix applied'],
+      resourcesFreed: '0 MB',
+      beforeMetrics: metrics,
+      afterMetrics: metrics,
+    };
+  }
+}

package/src/plugins/disk-health.ts

@@ -0,0 +1,128 @@
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from './plugin.interface.js';
+import { getPlatform } from '../platform/index.js';
+import { readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+export class DiskHealthPlugin implements WatchdogPlugin {
+  name = 'disk-health';
+  description = 'Monitor disk space, clean temporary files';
+  defaultInterval = 1800000;
+  private config: PluginConfig = {
+    enabled: true,
+    interval: 1800000,
+    autoFix: true,
+    thresholds: { warningPct: 80, criticalPct: 90, tempFileAgeDays: 7 },
+  };
+
+  configure(opts: PluginConfig): void {
+    this.config = { ...this.config, ...opts };
+  }
+
+  async check(): Promise<HealthCheck> {
+    const platform = getPlatform();
+    const disks = await platform.getDiskInfo();
+    const primary = disks[0];
+
+    if (!primary) {
+      return {
+        status: 'critical',
+        metrics: {},
+        message: 'No disk information available',
+        suggestedActions: [],
+      };
+    }
+
+    const diskUsedPct = primary.usedPct;
+    const diskFreeGB = primary.freeGB;
+    const diskTotalGB = primary.totalGB;
+
+    const warningPct = this.config.thresholds['warningPct'] ?? 80;
+    const criticalPct = this.config.thresholds['criticalPct'] ?? 90;
+
+    let status: HealthCheck['status'];
+    const suggestedActions: string[] = [];
+
+    if (diskUsedPct >= criticalPct) {
+      status = 'critical';
+      suggestedActions.push('Disk critically full — run fix() to clean temp files');
+    } else if (diskUsedPct >= warningPct) {
+      status = 'warning';
+      suggestedActions.push('Disk usage elevated — consider cleaning temp files');
+    } else {
+      status = 'healthy';
+    }
+
+    const message = `Disk ${primary.drive}: ${diskUsedPct.toFixed(1)}% used, ${diskFreeGB.toFixed(2)} GB free of ${diskTotalGB.toFixed(2)} GB`;
+
+    return {
+      status,
+      metrics: { diskUsedPct, diskFreeGB, diskTotalGB },
+      message,
+      suggestedActions,
+    };
+  }
+
+  async fix(): Promise<FixResult> {
+    const platform = getPlatform();
+
+    const disksBefore = await platform.getDiskInfo();
+    const primaryBefore = disksBefore[0];
+    const beforeMetrics: Record<string, number> = primaryBefore
+      ? {
+          diskUsedPct: primaryBefore.usedPct,
+          diskFreeGB: primaryBefore.freeGB,
+          diskTotalGB: primaryBefore.totalGB,
+        }
+      : {};
+
+    const tempDirs = platform.getTempDirs();
+    const tempFileAgeDays = this.config.thresholds['tempFileAgeDays'] ?? 7;
+    const ageThresholdMs = tempFileAgeDays * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+
+    const actionsKept: string[] = [];
+    let filesDeleted = 0;
+
+    for (const dir of tempDirs) {
+      let entries: string[];
+      try {
+        entries = readdirSync(dir);
+      } catch {
+        continue;
+      }
+
+      for (const entry of entries) {
+        const filePath = join(dir, entry);
+        try {
+          const st = statSync(filePath);
+          if (st.isFile() && now - st.mtimeMs > ageThresholdMs) {
+            unlinkSync(filePath);
+            filesDeleted++;
+          }
+        } catch {
+          // skip files we can't stat or delete
+        }
+      }
+    }
+
+    if (filesDeleted > 0) {
+      actionsKept.push(`Deleted ${filesDeleted} temp file(s) older than ${tempFileAgeDays} days`);
+    }
+
+    const disksAfter = await platform.getDiskInfo();
+    const primaryAfter = disksAfter[0];
+    const afterMetrics: Record<string, number> = primaryAfter
+      ? {
+          diskUsedPct: primaryAfter.usedPct,
+          diskFreeGB: primaryAfter.freeGB,
+          diskTotalGB: primaryAfter.totalGB,
+        }
+      : {};
+
+    const freedGB =
+      primaryBefore && primaryAfter ? primaryAfter.freeGB - primaryBefore.freeGB : 0;
+    const resourcesFreed = `Freed ~${(freedGB * 1024).toFixed(0)} MB disk space`;
+
+    return { actionsKept, resourcesFreed, beforeMetrics, afterMetrics };
+  }
+}

package/src/plugins/memory-monitor.ts

@@ -0,0 +1,70 @@
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from './plugin.interface.js';
+import { getPlatform } from '../platform/index.js';
+
+export class MemoryMonitorPlugin implements WatchdogPlugin {
+  name = 'memory-monitor';
+  description = 'Track RAM and page file usage, alert on high pressure';
+  defaultInterval = 120000;
+  private config: PluginConfig = {
+    enabled: true,
+    interval: 120000,
+    autoFix: false,
+    thresholds: { warningPct: 85, criticalPct: 95 },
+  };
+
+  configure(opts: PluginConfig): void {
+    this.config = { ...this.config, ...opts };
+  }
+
+  async check(): Promise<HealthCheck> {
+    const platform = getPlatform();
+    const mem = await platform.getMemoryInfo();
+
+    const ramUsedPct = mem.usedPct;
+    const ramFreeMB = mem.freeMB;
+    const ramTotalMB = mem.totalMB;
+    const pageFileMB = mem.pageFileUsageMB;
+
+    const metrics: Record<string, number> = {
+      ramUsedPct,
+      ramFreeMB,
+      ramTotalMB,
+      pageFileMB,
+    };
+
+    const warningPct = this.config.thresholds['warningPct'] ?? 85;
+    const criticalPct = this.config.thresholds['criticalPct'] ?? 95;
+
+    let status: HealthCheck['status'];
+    if (ramUsedPct >= criticalPct) {
+      status = 'critical';
+    } else if (ramUsedPct >= warningPct) {
+      status = 'warning';
+    } else {
+      status = 'healthy';
+    }
+
+    const message = `RAM: ${Math.round(ramUsedPct)}% used (${Math.round(ramFreeMB)} MB free of ${Math.round(ramTotalMB)} MB)`;
+
+    const suggestedActions: string[] = [];
+    if (status === 'critical') {
+      suggestedActions.push('RAM usage is critically high — consider closing applications or adding more memory');
+    } else if (status === 'warning') {
+      suggestedActions.push('RAM usage is elevated — monitor for further increases');
+    }
+
+    return { status, metrics, message, suggestedActions };
+  }
+
+  async fix(): Promise<FixResult> {
+    const result = await this.check();
+    const metrics = result.metrics;
+
+    return {
+      actionsKept: ['Alert pushed (no auto-fix for memory)'],
+      resourcesFreed: '0 MB (alert only)',
+      beforeMetrics: metrics,
+      afterMetrics: metrics,
+    };
+  }
+}

package/src/plugins/plugin-loader.ts

@@ -0,0 +1,27 @@
+import { WatchdogPlugin } from './plugin.interface.js';
+import { WatchdogConfig } from '../config.js';
+import { ProcessGuardPlugin } from './process-guard.js';
+import { MemoryMonitorPlugin } from './memory-monitor.js';
+import { DiskHealthPlugin } from './disk-health.js';
+import { StartupOptimizerPlugin } from './startup-optimizer.js';
+import { CpuMonitorPlugin } from './cpu-monitor.js';
+
+const pluginRegistry: Record<string, new () => WatchdogPlugin> = {
+  'process-guard': ProcessGuardPlugin,
+  'memory-monitor': MemoryMonitorPlugin,
+  'disk-health': DiskHealthPlugin,
+  'startup-optimizer': StartupOptimizerPlugin,
+  'cpu-monitor': CpuMonitorPlugin,
+};
+
+export function loadPlugins(config: WatchdogConfig): WatchdogPlugin[] {
+  const plugins: WatchdogPlugin[] = [];
+  for (const [name, PluginClass] of Object.entries(pluginRegistry)) {
+    const pluginConfig = config.plugins[name];
+    if (!pluginConfig || !pluginConfig.enabled) continue;
+    const plugin = new PluginClass();
+    plugin.configure(pluginConfig);
+    plugins.push(plugin);
+  }
+  return plugins;
+}

package/src/plugins/plugin.interface.ts

@@ -0,0 +1,31 @@
+export type HealthStatus = 'healthy' | 'warning' | 'critical';
+
+export interface HealthCheck {
+  status: HealthStatus;
+  metrics: Record<string, number>;
+  message: string;
+  suggestedActions: string[];
+}
+
+export interface FixResult {
+  actionsKept: string[];
+  resourcesFreed: string;
+  beforeMetrics: Record<string, number>;
+  afterMetrics: Record<string, number>;
+}
+
+export interface PluginConfig {
+  enabled: boolean;
+  interval: number;
+  thresholds: Record<string, number>;
+  autoFix: boolean;
+}
+
+export interface WatchdogPlugin {
+  name: string;
+  description: string;
+  defaultInterval: number;
+  check(): Promise<HealthCheck>;
+  fix(): Promise<FixResult>;
+  configure(opts: PluginConfig): void;
+}