process-watchdog 1.0.0

package/src/plugins/process-guard.ts

@@ -0,0 +1,165 @@
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from './plugin.interface.js';
+import { getPlatform, PlatformAdapter, ProcessInfo } from '../platform/index.js';
+
+const TARGET_NAMES = ['node', 'cmd', 'bash'] as const;
+type TargetName = (typeof TARGET_NAMES)[number];
+
+/** Safely get processes by name — returns [] if none found or platform throws */
+async function safeGetProcessesByName(platform: PlatformAdapter, name: string): Promise<ProcessInfo[]> {
+  try {
+    return await platform.getProcessesByName(name);
+  } catch {
+    return [];
+  }
+}
+
+export class ProcessGuardPlugin implements WatchdogPlugin {
+  name = 'process-guard';
+  description = 'Detect and kill orphaned processes before they accumulate';
+  defaultInterval = 300000;
+  private config: PluginConfig = {
+    enabled: true,
+    interval: 300000,
+    autoFix: true,
+    thresholds: { node: 50, cmd: 20, bash: 10 },
+  };
+
+  configure(opts: PluginConfig): void {
+    this.config = { ...this.config, ...opts };
+  }
+
+  async check(): Promise<HealthCheck> {
+    const platform = getPlatform();
+    const listeningPids = new Set(await platform.getListeningPids());
+
+    const counts: Record<string, number> = {};
+    const orphanCounts: Record<string, number> = {};
+    const warnings: string[] = [];
+    const suggestedActions: string[] = [];
+
+    for (const name of TARGET_NAMES) {
+      const procs = await safeGetProcessesByName(platform, name);
+      const total = procs.length;
+      const orphans = procs.filter((p) => !listeningPids.has(p.pid)).length;
+
+      counts[`${name}Count`] = total;
+      orphanCounts[`${name}Orphans`] = orphans;
+
+      const threshold = this.config.thresholds[name] ?? Infinity;
+      if (total > threshold) {
+        warnings.push(`${name}: ${total} processes exceeds threshold of ${threshold}`);
+        if (orphans > 0) {
+          suggestedActions.push(`Kill ${orphans} orphaned ${name} processes`);
+        }
+      }
+    }
+
+    const totalOrphans =
+      (orphanCounts['nodeOrphans'] ?? 0) +
+      (orphanCounts['cmdOrphans'] ?? 0) +
+      (orphanCounts['bashOrphans'] ?? 0);
+
+    const metrics: Record<string, number> = {
+      nodeCount: counts['nodeCount'] ?? 0,
+      cmdCount: counts['cmdCount'] ?? 0,
+      bashCount: counts['bashCount'] ?? 0,
+      nodeOrphans: orphanCounts['nodeOrphans'] ?? 0,
+      cmdOrphans: orphanCounts['cmdOrphans'] ?? 0,
+      bashOrphans: orphanCounts['bashOrphans'] ?? 0,
+      totalOrphans,
+    };
+
+    let status: HealthCheck['status'];
+    if (totalOrphans > 100) {
+      status = 'critical';
+    } else if (totalOrphans > 0 && warnings.length > 0) {
+      status = 'warning';
+    } else {
+      status = 'healthy';
+    }
+
+    const message =
+      warnings.length > 0 ? warnings.join('; ') : 'All process counts within thresholds';
+
+    return { status, metrics, message, suggestedActions };
+  }
+
+  async fix(): Promise<FixResult> {
+    const platform = getPlatform();
+    const listeningPids = new Set(await platform.getListeningPids());
+
+    // Capture before metrics
+    const beforeMetrics: Record<string, number> = {};
+    for (const name of TARGET_NAMES) {
+      const procs = await safeGetProcessesByName(platform, name);
+      beforeMetrics[`${name}Count`] = procs.length;
+      beforeMetrics[`${name}Orphans`] = procs.filter((p) => !listeningPids.has(p.pid)).length;
+    }
+
+    const actionsKept: string[] = [];
+    let totalMemoryFreedMB = 0;
+
+    // Protect only: this process, its parent, and processes listening on ports (dev servers)
+    const selfPid = process.pid;
+    const parentPid = process.ppid;
+    const protectedPids = new Set<number>(
+      [selfPid, parentPid, ...listeningPids].filter((p): p is number => typeof p === 'number'),
+    );
+
+    // Kill orphans only when process count exceeds threshold
+    for (const name of TARGET_NAMES) {
+      const procs = await safeGetProcessesByName(platform, name);
+      const threshold = this.config.thresholds[name] ?? Infinity;
+
+      if (procs.length <= threshold) continue; // Within limits — skip
+
+      const orphans = procs.filter((p) => !listeningPids.has(p.pid) && !protectedPids.has(p.pid));
+
+      let killed = 0;
+      for (const proc of orphans) {
+        const success = await platform.killProcess(proc.pid);
+        if (success) {
+          killed++;
+          totalMemoryFreedMB += proc.memoryMB ?? 0;
+        }
+      }
+
+      if (orphans.length > 0) {
+        actionsKept.push(`Killed ${killed}/${orphans.length} orphaned ${name} processes`);
+      }
+    }
+
+    // Best-effort: clean up low-CPU conhost processes (skip any that were running at snapshot time)
+    try {
+      const conhosts = await safeGetProcessesByName(platform, 'conhost');
+      for (const proc of conhosts) {
+        if (proc.cpu < 0.1 && !protectedPids.has(proc.pid)) {
+          const success = await platform.killProcess(proc.pid);
+          if (success) {
+            totalMemoryFreedMB += proc.memoryMB ?? 0;
+          }
+        }
+      }
+    } catch {
+      // best-effort, ignore errors
+    }
+
+    // Capture after metrics (best-effort — system may be in transition after kills)
+    let afterListeningPids: Set<number>;
+    try {
+      afterListeningPids = new Set(await platform.getListeningPids());
+    } catch {
+      afterListeningPids = new Set<number>();
+    }
+    const afterMetrics: Record<string, number> = {};
+    for (const name of TARGET_NAMES) {
+      const procs = await safeGetProcessesByName(platform, name);
+      afterMetrics[`${name}Count`] = procs.length;
+      afterMetrics[`${name}Orphans`] = procs.filter((p) => !afterListeningPids.has(p.pid)).length;
+    }
+
+    const resourcesFreed = `Freed ~${Math.round(totalMemoryFreedMB)} MB RAM`;
+
+    return { actionsKept, resourcesFreed, beforeMetrics, afterMetrics };
+  }
+}

package/src/plugins/startup-optimizer.ts

@@ -0,0 +1,103 @@
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from './plugin.interface.js';
+import { getPlatform } from '../platform/index.js';
+
+const KNOWN_BLOAT = [
+  'Docker Desktop',
+  'GoogleDriveFS',
+  'Figma Agent',
+  'CiscoSpark',
+  'CiscoMeetingDaemon',
+  'EasySettingBox',
+  'com.todesktop',
+];
+
+export class StartupOptimizerPlugin implements WatchdogPlugin {
+  name = 'startup-optimizer';
+  description = 'Manage startup items to reduce boot resource usage';
+  defaultInterval = 0;
+  private config: PluginConfig = {
+    enabled: true,
+    interval: 0,
+    autoFix: false,
+    thresholds: {},
+  };
+
+  configure(opts: PluginConfig): void {
+    this.config = { ...this.config, ...opts };
+  }
+
+  async check(): Promise<HealthCheck> {
+    const platform = getPlatform();
+    const items = await platform.getStartupItems();
+
+    const enabledItems = items.filter((item) => item.enabled);
+    const startupItemCount = enabledItems.length;
+
+    const bloatItems = enabledItems.filter((item) =>
+      KNOWN_BLOAT.some((bloat) => item.name.includes(bloat)),
+    );
+    const bloatItemCount = bloatItems.length;
+
+    const suggestedActions: string[] = [];
+    if (bloatItemCount > 0) {
+      suggestedActions.push(
+        `Disable ${bloatItemCount} bloat startup item(s): ${bloatItems.map((b) => b.name).join(', ')}`,
+      );
+    }
+
+    const status: HealthCheck['status'] = bloatItemCount > 3 ? 'warning' : 'healthy';
+    const message = `${startupItemCount} startup items enabled, ${bloatItemCount} identified as bloat`;
+
+    return {
+      status,
+      metrics: { startupItemCount, bloatItemCount },
+      message,
+      suggestedActions,
+    };
+  }
+
+  async fix(): Promise<FixResult> {
+    const platform = getPlatform();
+
+    const itemsBefore = await platform.getStartupItems();
+    const enabledBefore = itemsBefore.filter((item) => item.enabled);
+    const bloatBefore = enabledBefore.filter((item) =>
+      KNOWN_BLOAT.some((bloat) => item.name.includes(bloat)),
+    );
+
+    const beforeMetrics: Record<string, number> = {
+      startupItemCount: enabledBefore.length,
+      bloatItemCount: bloatBefore.length,
+    };
+
+    const actionsKept: string[] = [];
+    let disabledCount = 0;
+
+    for (const item of bloatBefore) {
+      try {
+        const success = await platform.disableStartupItem(item.name);
+        if (success) {
+          disabledCount++;
+          actionsKept.push(`Disabled startup item: ${item.name}`);
+        }
+      } catch {
+        // skip items that fail to disable
+      }
+    }
+
+    const itemsAfter = await platform.getStartupItems();
+    const enabledAfter = itemsAfter.filter((item) => item.enabled);
+    const bloatAfter = enabledAfter.filter((item) =>
+      KNOWN_BLOAT.some((bloat) => item.name.includes(bloat)),
+    );
+
+    const afterMetrics: Record<string, number> = {
+      startupItemCount: enabledAfter.length,
+      bloatItemCount: bloatAfter.length,
+    };
+
+    const resourcesFreed = `Disabled ${disabledCount} startup item(s)`;
+
+    return { actionsKept, resourcesFreed, beforeMetrics, afterMetrics };
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,53 @@
+import { WatchdogPlugin } from './plugins/plugin.interface.js';
+
+interface SchedulerOptions {
+  autoFix: Record<string, boolean>;
+}
+
+export class Scheduler {
+  private plugins: WatchdogPlugin[];
+  private options: SchedulerOptions;
+  private timers: NodeJS.Timeout[] = [];
+  private running = false;
+
+  constructor(plugins: WatchdogPlugin[], options: SchedulerOptions) {
+    this.plugins = plugins;
+    this.options = options;
+  }
+
+  start(overrideIntervalMs?: number): void {
+    if (this.running) return;
+    this.running = true;
+
+    for (const plugin of this.plugins) {
+      const interval = overrideIntervalMs ?? plugin.defaultInterval;
+      if (interval <= 0) continue;
+
+      const run = async () => {
+        if (!this.running) return;
+        try {
+          const result = await plugin.check();
+          const shouldFix = this.options.autoFix[plugin.name] &&
+            (result.status === 'critical' || result.status === 'warning');
+          if (shouldFix) {
+            await plugin.fix();
+          }
+        } catch (err) {
+          console.error(`[watchdog] ${plugin.name} error:`, err);
+        }
+      };
+
+      run(); // Run immediately
+      const timer = setInterval(run, interval);
+      this.timers.push(timer);
+    }
+  }
+
+  stop(): void {
+    this.running = false;
+    for (const timer of this.timers) clearInterval(timer);
+    this.timers = [];
+  }
+
+  isRunning(): boolean { return this.running; }
+}

package/src/store/history.ts

@@ -0,0 +1,90 @@
+import Database from 'better-sqlite3';
+
+export interface HistoryRow {
+  id: number;
+  plugin: string;
+  type: string;
+  status: string;
+  metrics: string | null;
+  actions: string | null;
+  message: string | null;
+  timestamp: string;
+}
+
+export class HistoryStore {
+  private db: Database.Database;
+
+  constructor(dbPath: string = './watchdog.db') {
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS history (
+        id        INTEGER PRIMARY KEY AUTOINCREMENT,
+        plugin    TEXT    NOT NULL,
+        type      TEXT    NOT NULL,
+        status    TEXT    NOT NULL,
+        metrics   TEXT,
+        actions   TEXT,
+        message   TEXT,
+        timestamp TEXT    NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+  }
+
+  recordCheck(
+    plugin: string,
+    status: string,
+    metrics: Record<string, unknown>,
+    message: string,
+  ): void {
+    const stmt = this.db.prepare(
+      `INSERT INTO history (plugin, type, status, metrics, message)
+       VALUES (?, 'check', ?, ?, ?)`,
+    );
+    stmt.run(plugin, status, JSON.stringify(metrics), message);
+  }
+
+  recordFix(plugin: string, actions: string[], resourcesFreed: string): void {
+    const stmt = this.db.prepare(
+      `INSERT INTO history (plugin, type, status, actions, message)
+       VALUES (?, 'fix', 'fixed', ?, ?)`,
+    );
+    stmt.run(plugin, JSON.stringify(actions), resourcesFreed);
+  }
+
+  getHistory(plugin: string | null, limit: number): HistoryRow[] {
+    if (plugin !== null) {
+      const stmt = this.db.prepare(
+        `SELECT * FROM history WHERE plugin = ? ORDER BY id DESC LIMIT ?`,
+      );
+      return stmt.all(plugin, limit) as HistoryRow[];
+    }
+    const stmt = this.db.prepare(
+      `SELECT * FROM history ORDER BY id DESC LIMIT ?`,
+    );
+    return stmt.all(limit) as HistoryRow[];
+  }
+
+  getLastChecks(): Record<string, HistoryRow> {
+    const stmt = this.db.prepare(`
+      SELECT h.*
+      FROM history h
+      INNER JOIN (
+        SELECT plugin, MAX(id) AS max_id
+        FROM history
+        WHERE type = 'check'
+        GROUP BY plugin
+      ) latest ON h.id = latest.max_id
+    `);
+    const rows = stmt.all() as HistoryRow[];
+    const result: Record<string, HistoryRow> = {};
+    for (const row of rows) {
+      result[row.plugin] = row;
+    }
+    return result;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/tests/api/routes.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import supertest from 'supertest';
+import { existsSync, unlinkSync } from 'fs';
+import { HistoryStore } from '../../src/store/history.js';
+import { WatchdogPlugin, HealthCheck, FixResult, PluginConfig } from '../../src/plugins/plugin.interface.js';
+import { loadConfig } from '../../src/config.js';
+import { createApp } from '../../src/api/server.js';
+
+const TEST_DB = './test-routes-api.db';
+
+class MockPlugin implements WatchdogPlugin {
+  name = 'process-guard';
+  description = 'Mock process guard plugin';
+  defaultInterval = 300000;
+
+  async check(): Promise<HealthCheck> {
+    return {
+      status: 'healthy',
+      metrics: { nodeCount: 2 },
+      message: 'All good',
+      suggestedActions: [],
+    };
+  }
+
+  async fix(): Promise<FixResult> {
+    return {
+      actionsKept: [],
+      resourcesFreed: '0MB',
+      beforeMetrics: {},
+      afterMetrics: {},
+    };
+  }
+
+  configure(_opts: PluginConfig): void {}
+}
+
+let request: ReturnType<typeof supertest>;
+let store: HistoryStore;
+
+beforeAll(async () => {
+  const config = await loadConfig({ port: 3400 });
+  store = new HistoryStore(TEST_DB);
+  // Seed with one record
+  store.recordCheck('process-guard', 'healthy', { nodeCount: 1 }, 'Seeded check');
+
+  const plugins: WatchdogPlugin[] = [new MockPlugin()];
+  const app = createApp(store, plugins, config);
+  request = supertest(app);
+});
+
+afterAll(() => {
+  store.close();
+  if (existsSync(TEST_DB)) {
+    unlinkSync(TEST_DB);
+  }
+});
+
+describe('GET /api/v1/health', () => {
+  it('returns 200 with service and plugins object', async () => {
+    const res = await request.get('/api/v1/health');
+    expect(res.status).toBe(200);
+    expect(res.body.service).toBe('process-watchdog');
+    expect(res.body).toHaveProperty('plugins');
+    expect(typeof res.body.plugins).toBe('object');
+    expect(res.body).toHaveProperty('status');
+    expect(res.body).toHaveProperty('uptime');
+  });
+});
+
+describe('GET /api/v1/plugins', () => {
+  it('returns array with length > 0 and each item has name', async () => {
+    const res = await request.get('/api/v1/plugins');
+    expect(res.status).toBe(200);
+    expect(Array.isArray(res.body)).toBe(true);
+    expect(res.body.length).toBeGreaterThan(0);
+    for (const plugin of res.body) {
+      expect(plugin).toHaveProperty('name');
+    }
+  });
+});
+
+describe('GET /api/v1/history', () => {
+  it('returns array', async () => {
+    const res = await request.get('/api/v1/history');
+    expect(res.status).toBe(200);
+    expect(Array.isArray(res.body)).toBe(true);
+  });
+});
+
+describe('GET /api/v1/config', () => {
+  it('returns object with port 3400', async () => {
+    const res = await request.get('/api/v1/config');
+    expect(res.status).toBe(200);
+    expect(typeof res.body).toBe('object');
+    expect(res.body.port).toBe(3400);
+  });
+});
+
+describe('GET /api/v1/plugins/process-guard', () => {
+  it('returns 200 with name and history', async () => {
+    const res = await request.get('/api/v1/plugins/process-guard');
+    expect(res.status).toBe(200);
+    expect(res.body.name).toBe('process-guard');
+    expect(Array.isArray(res.body.history)).toBe(true);
+  });
+});
+
+describe('GET /api/v1/plugins/nonexistent', () => {
+  it('returns 404', async () => {
+    const res = await request.get('/api/v1/plugins/nonexistent');
+    expect(res.status).toBe(404);
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { loadConfig } from '../src/config.js';
+
+describe('loadConfig', () => {
+  it('returns defaults when no user overrides', async () => {
+    const config = await loadConfig();
+    expect(config.port).toBe(3400);
+    expect(config.plugins['process-guard'].enabled).toBe(true);
+    expect(config.plugins['process-guard'].thresholds.node).toBe(50);
+  });
+
+  it('deep-merges overrides without clobbering sibling keys', async () => {
+    const config = await loadConfig({
+      plugins: {
+        'process-guard': {
+          thresholds: { node: 100 },
+        },
+      },
+    });
+    expect(config.plugins['process-guard'].thresholds.node).toBe(100);
+    // enabled should still be true from defaults
+    expect(config.plugins['process-guard'].enabled).toBe(true);
+  });
+});

package/tests/platform/windows.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { WindowsPlatform } from '../../src/platform/windows.js';
+
+const describeWindows = process.platform === 'win32' ? describe : describe.skip;
+
+describeWindows('WindowsPlatform', () => {
+  const platform = new WindowsPlatform();
+
+  it('getProcessesByName returns node processes with required fields', async () => {
+    const procs = await platform.getProcessesByName('node');
+    expect(Array.isArray(procs)).toBe(true);
+    expect(procs.length).toBeGreaterThanOrEqual(1);
+    const first = procs[0];
+    expect(typeof first.pid).toBe('number');
+    expect(typeof first.name).toBe('string');
+    expect(typeof first.memoryMB).toBe('number');
+    expect(first.memoryMB).toBeGreaterThanOrEqual(0);
+  });
+
+  it('getMemoryInfo returns valid memory stats', async () => {
+    const mem = await platform.getMemoryInfo();
+    expect(mem.totalMB).toBeGreaterThan(0);
+    expect(mem.freeMB).toBeGreaterThan(0);
+    expect(mem.usedPct).toBeGreaterThanOrEqual(0);
+    expect(mem.usedPct).toBeLessThanOrEqual(100);
+  });
+
+  it('getDiskInfo returns at least one drive with valid data', async () => {
+    const disks = await platform.getDiskInfo();
+    expect(Array.isArray(disks)).toBe(true);
+    expect(disks.length).toBeGreaterThanOrEqual(1);
+    const first = disks[0];
+    expect(first.drive).toMatch(/^[A-Z]:$/);
+    expect(first.totalGB).toBeGreaterThan(0);
+  });
+
+  it('getListeningPids returns array of numbers', async () => {
+    const pids = await platform.getListeningPids();
+    expect(Array.isArray(pids)).toBe(true);
+    for (const pid of pids) {
+      expect(typeof pid).toBe('number');
+    }
+  });
+
+  it('getStartupItems returns an array', async () => {
+    const items = await platform.getStartupItems();
+    expect(Array.isArray(items)).toBe(true);
+  });
+
+  it('getTempDirs returns non-empty string array', () => {
+    const dirs = platform.getTempDirs();
+    expect(Array.isArray(dirs)).toBe(true);
+    expect(dirs.length).toBeGreaterThan(0);
+    for (const dir of dirs) {
+      expect(typeof dir).toBe('string');
+      expect(dir.length).toBeGreaterThan(0);
+    }
+  });
+});

package/tests/plugins/cpu-monitor.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { CpuMonitorPlugin } from '../../src/plugins/cpu-monitor.js';
+
+const describeWindows = process.platform === 'win32' ? describe : describe.skip;
+
+describeWindows('CpuMonitorPlugin', () => {
+  let plugin: CpuMonitorPlugin;
+
+  beforeAll(() => {
+    plugin = new CpuMonitorPlugin();
+    plugin.configure({
+      enabled: true,
+      interval: 120000,
+      autoFix: false,
+      thresholds: { warningPct: 75, criticalPct: 90 },
+    });
+  });
+
+  it('check() returns cpuUsedPct between 0 and 100', async () => {
+    const result = await plugin.check();
+    expect(['healthy', 'warning', 'critical']).toContain(result.status);
+    expect(result.metrics).toHaveProperty('cpuUsedPct');
+    expect(result.metrics.cpuUsedPct).toBeGreaterThanOrEqual(0);
+    expect(result.metrics.cpuUsedPct).toBeLessThanOrEqual(100);
+  }, 15000);
+
+  it('check() returns sampleCount as a positive number', async () => {
+    const result = await plugin.check();
+    expect(result.metrics).toHaveProperty('sampleCount');
+    expect(result.metrics.sampleCount).toBeGreaterThan(0);
+  }, 15000);
+
+  it('check() returns a non-empty message', async () => {
+    const result = await plugin.check();
+    expect(typeof result.message).toBe('string');
+    expect(result.message.length).toBeGreaterThan(0);
+  }, 15000);
+
+  it('check() returns warning/critical when criticalPct threshold is very low', async () => {
+    plugin.configure({
+      enabled: true,
+      interval: 120000,
+      autoFix: false,
+      thresholds: { warningPct: 0, criticalPct: 1 },
+    });
+    const result = await plugin.check();
+    expect(['warning', 'critical']).toContain(result.status);
+    // Reset
+    plugin.configure({
+      enabled: true,
+      interval: 120000,
+      autoFix: false,
+      thresholds: { warningPct: 75, criticalPct: 90 },
+    });
+  }, 15000);
+
+  it('fix() returns valid FixResult (alert-only)', async () => {
+    const result = await plugin.fix();
+    expect(result).toHaveProperty('actionsKept');
+    expect(result).toHaveProperty('resourcesFreed');
+    expect(result).toHaveProperty('beforeMetrics');
+    expect(result).toHaveProperty('afterMetrics');
+    expect(Array.isArray(result.actionsKept)).toBe(true);
+    expect(result.beforeMetrics).toHaveProperty('cpuUsedPct');
+    expect(result.afterMetrics).toHaveProperty('cpuUsedPct');
+    // Before and after should be identical for alert-only
+    expect(result.beforeMetrics.cpuUsedPct).toBe(result.afterMetrics.cpuUsedPct);
+  }, 15000);
+});