@shykaruu/jarvis-brain 0.4.0

package/src/observers/file-watcher.ts

@@ -0,0 +1,124 @@
+/**
+ * FileWatcher - Monitors file system changes
+ *
+ * Watches specified directories recursively and emits events when files change.
+ * Includes debouncing to avoid duplicate rapid-fire events.
+ */
+
+import { watch, type FSWatcher } from 'node:fs';
+import type { Observer, ObserverEvent, ObserverEventHandler } from './index';
+
+type DebounceEntry = {
+  path: string;
+  timestamp: number;
+};
+
+export class FileWatcher implements Observer {
+  name = 'file-watcher';
+  private watchers: FSWatcher[] = [];
+  private paths: string[];
+  private handler: ObserverEventHandler | null = null;
+  private running = false;
+  private recentChanges: Map<string, number> = new Map();
+  private debounceMs = 100; // Ignore duplicate events within 100ms
+
+  constructor(paths: string[]) {
+    this.paths = paths;
+  }
+
+  async start(): Promise<void> {
+    if (this.running) {
+      console.log('[file-watcher] Already running');
+      return;
+    }
+
+    console.log('[file-watcher] Starting file system monitoring...');
+
+    for (const path of this.paths) {
+      try {
+        const watcher = watch(path, { recursive: true }, (eventType, filename) => {
+          this.handleFileEvent(path, eventType, filename);
+        });
+
+        watcher.on('error', (error) => {
+          console.error(`[file-watcher] Error watching ${path}:`, error);
+        });
+
+        this.watchers.push(watcher);
+        console.log(`[file-watcher] Watching: ${path}`);
+      } catch (error) {
+        console.error(`[file-watcher] Failed to watch ${path}:`, error);
+      }
+    }
+
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    console.log('[file-watcher] Stopping file system monitoring...');
+
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+
+    this.watchers = [];
+    this.recentChanges.clear();
+    this.running = false;
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  private handleFileEvent(
+    basePath: string,
+    eventType: 'rename' | 'change',
+    filename: string | null
+  ): void {
+    if (!filename || !this.handler) {
+      return;
+    }
+
+    const fullPath = `${basePath}/${filename}`;
+    const now = Date.now();
+
+    // Debounce: skip if same file changed within debounceMs
+    const lastChange = this.recentChanges.get(fullPath);
+    if (lastChange && now - lastChange < this.debounceMs) {
+      return;
+    }
+
+    this.recentChanges.set(fullPath, now);
+
+    // Clean up old entries to prevent memory leak
+    if (this.recentChanges.size > 1000) {
+      const cutoff = now - this.debounceMs * 2;
+      for (const [path, timestamp] of this.recentChanges.entries()) {
+        if (timestamp < cutoff) {
+          this.recentChanges.delete(path);
+        }
+      }
+    }
+
+    const event: ObserverEvent = {
+      type: 'file_change',
+      data: {
+        path: fullPath,
+        eventType,
+        filename,
+        basePath,
+      },
+      timestamp: now,
+    };
+
+    this.handler(event);
+  }
+}

package/src/observers/index.ts

@@ -0,0 +1,159 @@
+/**
+ * Observer Layer - Monitors system events and emits observations to the Vault
+ *
+ * All observers implement a common interface and emit standardized events.
+ */
+
+// Common Observer Interface
+export type ObserverEvent = {
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+};
+
+export type ObserverEventHandler = (event: ObserverEvent) => void;
+
+export interface Observer {
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isRunning(): boolean;
+  onEvent(handler: ObserverEventHandler): void;
+}
+
+// Export all observers
+export { FileWatcher } from './file-watcher';
+export { ClipboardMonitor } from './clipboard';
+export { NotificationListener } from './notifications';
+export { ProcessMonitor } from './processes';
+export { CalendarSync } from './calendar';
+export { EmailSync } from './email';
+
+/**
+ * ObserverManager - Centralized coordinator for all observers
+ */
+export class ObserverManager {
+  private observers: Map<string, Observer> = new Map();
+  private eventHandler: ObserverEventHandler | null = null;
+
+  /**
+   * Register a new observer
+   */
+  register(observer: Observer): void {
+    this.observers.set(observer.name, observer);
+
+    // If we already have a handler, apply it to the new observer
+    if (this.eventHandler) {
+      observer.onEvent(this.eventHandler);
+    }
+
+    console.log(`[ObserverManager] Registered observer: ${observer.name}`);
+  }
+
+  /**
+   * Set the global event handler for all observers
+   * This is typically the Vault's observation ingestion function
+   */
+  setEventHandler(handler: ObserverEventHandler): void {
+    this.eventHandler = handler;
+
+    // Apply handler to all registered observers
+    for (const observer of this.observers.values()) {
+      observer.onEvent(handler);
+    }
+
+    console.log(`[ObserverManager] Event handler configured for ${this.observers.size} observers`);
+  }
+
+  /**
+   * Start all registered observers
+   */
+  async startAll(): Promise<void> {
+    console.log('[ObserverManager] Starting all observers...');
+
+    const promises = Array.from(this.observers.values()).map(async (observer) => {
+      try {
+        await observer.start();
+        console.log(`[ObserverManager] ✓ Started ${observer.name}`);
+      } catch (error) {
+        console.error(`[ObserverManager] ✗ Failed to start ${observer.name}:`, error);
+      }
+    });
+
+    await Promise.all(promises);
+    console.log('[ObserverManager] All observers started');
+  }
+
+  /**
+   * Stop all registered observers
+   */
+  async stopAll(): Promise<void> {
+    console.log('[ObserverManager] Stopping all observers...');
+
+    const promises = Array.from(this.observers.values()).map(async (observer) => {
+      try {
+        await observer.stop();
+        console.log(`[ObserverManager] ✓ Stopped ${observer.name}`);
+      } catch (error) {
+        console.error(`[ObserverManager] ✗ Failed to stop ${observer.name}:`, error);
+      }
+    });
+
+    await Promise.all(promises);
+    console.log('[ObserverManager] All observers stopped');
+  }
+
+  /**
+   * Start a specific observer by name
+   */
+  async startObserver(name: string): Promise<void> {
+    const observer = this.observers.get(name);
+    if (!observer) {
+      throw new Error(`Observer not found: ${name}`);
+    }
+
+    if (observer.isRunning()) {
+      console.log(`[ObserverManager] Observer ${name} is already running`);
+      return;
+    }
+
+    await observer.start();
+    console.log(`[ObserverManager] Started ${name}`);
+  }
+
+  /**
+   * Stop a specific observer by name
+   */
+  async stopObserver(name: string): Promise<void> {
+    const observer = this.observers.get(name);
+    if (!observer) {
+      throw new Error(`Observer not found: ${name}`);
+    }
+
+    if (!observer.isRunning()) {
+      console.log(`[ObserverManager] Observer ${name} is not running`);
+      return;
+    }
+
+    await observer.stop();
+    console.log(`[ObserverManager] Stopped ${name}`);
+  }
+
+  /**
+   * Get running status of all observers
+   */
+  getStatus(): Record<string, boolean> {
+    const status: Record<string, boolean> = {};
+    for (const [name, observer] of this.observers) {
+      status[name] = observer.isRunning();
+    }
+    return status;
+  }
+
+  /**
+   * List all registered observer names
+   */
+  listObservers(): string[] {
+    return Array.from(this.observers.keys());
+  }
+}

package/src/observers/notifications.ts

@@ -0,0 +1,197 @@
+/**
+ * NotificationListener — D-Bus Notification Monitor (Linux/WSL2)
+ *
+ * Monitors system notifications by watching D-Bus for
+ * org.freedesktop.Notifications.Notify method calls.
+ * Parses notification fields: app_name, summary, body, urgency.
+ *
+ * Graceful: if dbus-monitor is not found, logs warning and stays no-op.
+ */
+
+import type { Observer, ObserverEventHandler } from './index';
+import type { Subprocess } from 'bun';
+
+type NotificationData = {
+  app: string;
+  title: string;
+  body: string;
+  urgency: string;
+};
+
+export class NotificationListener implements Observer {
+  name = 'notifications';
+  private running = false;
+  private handler: ObserverEventHandler | null = null;
+  private process: Subprocess | null = null;
+  private available = false;
+
+  async start(): Promise<void> {
+    this.running = true;
+
+    // Check if dbus-monitor exists
+    try {
+      const check = Bun.spawnSync(['which', 'dbus-monitor']);
+      if (check.exitCode !== 0) {
+        console.log('[notifications] dbus-monitor not found — notification monitoring disabled');
+        return;
+      }
+      this.available = true;
+    } catch {
+      console.log('[notifications] Cannot check for dbus-monitor — notification monitoring disabled');
+      return;
+    }
+
+    // Spawn dbus-monitor watching for Notify signals
+    try {
+      this.process = Bun.spawn(
+        [
+          'dbus-monitor',
+          '--session',
+          "interface='org.freedesktop.Notifications',member='Notify'",
+        ],
+        {
+          stdout: 'pipe',
+          stderr: 'ignore',
+        }
+      );
+
+      console.log('[notifications] Observer started — monitoring D-Bus notifications');
+
+      // Parse stdout in background
+      this.readOutput();
+    } catch (err) {
+      console.error('[notifications] Failed to start dbus-monitor:', err);
+      this.available = false;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+
+    if (this.process) {
+      try {
+        this.process.kill();
+      } catch {
+        // Ignore
+      }
+      this.process = null;
+    }
+
+    console.log('[notifications] Observer stopped');
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  /**
+   * Read dbus-monitor output and parse notification blocks.
+   *
+   * D-Bus notification format (method_call):
+   *   method call ... dest=org.freedesktop.Notifications ... member=Notify
+   *   string "app_name"
+   *   uint32 ...
+   *   string "icon"
+   *   string "summary"
+   *   string "body"
+   *   array [ ... ]
+   *   ...
+   */
+  private async readOutput(): Promise<void> {
+    if (!this.process?.stdout) return;
+
+    const reader = (this.process.stdout as ReadableStream<Uint8Array>).getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    // State machine for parsing method_call blocks
+    let inMethodCall = false;
+    let stringIndex = 0;
+    let currentNotification: Partial<NotificationData> = {};
+
+    try {
+      while (this.running) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+
+          // Detect start of a new method call
+          if (trimmed.startsWith('method call') && trimmed.includes('member=Notify')) {
+            inMethodCall = true;
+            stringIndex = 0;
+            currentNotification = {};
+            continue;
+          }
+
+          // Detect start of next method/signal (end of current block)
+          if (inMethodCall && (trimmed.startsWith('method call') || trimmed.startsWith('signal') || trimmed.startsWith('method return'))) {
+            // Emit the notification if we got enough data
+            this.emitNotification(currentNotification);
+            inMethodCall = trimmed.startsWith('method call') && trimmed.includes('member=Notify');
+            stringIndex = 0;
+            currentNotification = {};
+            continue;
+          }
+
+          if (!inMethodCall) continue;
+
+          // Parse string values — the Notify method has these string args in order:
+          // 0: app_name, 1: (replaces_id is uint32, skip), 2: icon, 3: summary, 4: body
+          const stringMatch = trimmed.match(/^string\s+"(.*)"/);
+          if (stringMatch) {
+            const val = stringMatch[1];
+            switch (stringIndex) {
+              case 0: currentNotification.app = val; break;
+              // index 1 is icon (we skip)
+              case 1: break; // icon
+              case 2: currentNotification.title = val; break;
+              case 3: currentNotification.body = val; break;
+            }
+            stringIndex++;
+            continue;
+          }
+
+          // Parse urgency from hints dict (byte value)
+          const urgencyMatch = trimmed.match(/byte\s+(\d+)/);
+          if (urgencyMatch) {
+            const urgencyLevel = parseInt(urgencyMatch[1]!);
+            currentNotification.urgency =
+              urgencyLevel === 2 ? 'critical' :
+              urgencyLevel === 1 ? 'normal' :
+              'low';
+          }
+        }
+      }
+    } catch (err) {
+      if (this.running) {
+        console.error('[notifications] Read error:', err);
+      }
+    }
+  }
+
+  private emitNotification(data: Partial<NotificationData>): void {
+    if (!data.title && !data.body) return;
+    if (!this.handler) return;
+
+    this.handler({
+      type: 'notification',
+      data: {
+        app: data.app ?? 'unknown',
+        title: data.title ?? '',
+        body: data.body ?? '',
+        urgency: data.urgency ?? 'normal',
+      },
+      timestamp: Date.now(),
+    });
+  }
+}

package/src/observers/observers.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Tests for Observer Layer
+ */
+
+import { test, expect, describe, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  ObserverManager,
+  FileWatcher,
+  ClipboardMonitor,
+  ProcessMonitor,
+  NotificationListener,
+  CalendarSync,
+  EmailSync,
+  type ObserverEvent,
+} from './index';
+
+// Use an isolated temp dir instead of /tmp to avoid slow recursive watches on CI
+let testDir: string;
+beforeAll(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'jarvis-test-'));
+});
+afterAll(() => {
+  try { rmSync(testDir, { recursive: true }); } catch {}
+});
+
+describe('ObserverManager', () => {
+  test('registers observers', () => {
+    const manager = new ObserverManager();
+    const watcher = new FileWatcher([testDir]);
+
+    manager.register(watcher);
+
+    expect(manager.listObservers()).toEqual(['file-watcher']);
+  });
+
+  test('propagates event handler to observers', () => {
+    const manager = new ObserverManager();
+    const watcher = new FileWatcher([testDir]);
+
+    manager.register(watcher);
+
+    let handlerCalled = false;
+    manager.setEventHandler(() => {
+      handlerCalled = true;
+    });
+
+    // Handler should be set on the observer
+    expect(handlerCalled).toBe(false); // Not called yet, just registered
+  });
+
+  test('starts and stops all observers', async () => {
+    const manager = new ObserverManager();
+    const watcher = new FileWatcher([testDir]);
+    const clipboard = new ClipboardMonitor(5000);
+
+    manager.register(watcher);
+    manager.register(clipboard);
+
+    await manager.startAll();
+
+    const status = manager.getStatus();
+    expect(status['file-watcher']).toBe(true);
+    expect(status['clipboard']).toBe(true);
+
+    await manager.stopAll();
+
+    const statusAfter = manager.getStatus();
+    expect(statusAfter['file-watcher']).toBe(false);
+    expect(statusAfter['clipboard']).toBe(false);
+  });
+
+  test('starts and stops individual observers', async () => {
+    const manager = new ObserverManager();
+    const watcher = new FileWatcher([testDir]);
+
+    manager.register(watcher);
+
+    await manager.startObserver('file-watcher');
+    expect(manager.getStatus()['file-watcher']).toBe(true);
+
+    await manager.stopObserver('file-watcher');
+    expect(manager.getStatus()['file-watcher']).toBe(false);
+  });
+});
+
+describe('FileWatcher', () => {
+  test('starts and stops', async () => {
+    const watcher = new FileWatcher([testDir]);
+
+    expect(watcher.isRunning()).toBe(false);
+
+    await watcher.start();
+    expect(watcher.isRunning()).toBe(true);
+
+    await watcher.stop();
+    expect(watcher.isRunning()).toBe(false);
+  });
+
+  test('prevents double start', async () => {
+    const watcher = new FileWatcher([testDir]);
+
+    await watcher.start();
+    await watcher.start(); // Should not throw
+
+    expect(watcher.isRunning()).toBe(true);
+
+    await watcher.stop();
+  });
+});
+
+describe('ClipboardMonitor', () => {
+  test('starts and stops', async () => {
+    const clipboard = new ClipboardMonitor(5000);
+
+    expect(clipboard.isRunning()).toBe(false);
+
+    await clipboard.start();
+    expect(clipboard.isRunning()).toBe(true);
+
+    await clipboard.stop();
+    expect(clipboard.isRunning()).toBe(false);
+  });
+
+  test('uses custom poll interval', async () => {
+    const clipboard = new ClipboardMonitor(10000);
+
+    await clipboard.start();
+    expect(clipboard.isRunning()).toBe(true);
+
+    await clipboard.stop();
+  });
+});
+
+describe('ProcessMonitor', () => {
+  test('starts and stops', async () => {
+    const monitor = new ProcessMonitor(10000);
+
+    expect(monitor.isRunning()).toBe(false);
+
+    await monitor.start();
+    expect(monitor.isRunning()).toBe(true);
+
+    await monitor.stop();
+    expect(monitor.isRunning()).toBe(false);
+  });
+
+  test('gets process list', async () => {
+    const monitor = new ProcessMonitor(10000);
+
+    const processes = await monitor.getProcessList();
+
+    expect(Array.isArray(processes)).toBe(true);
+    expect(processes.length).toBeGreaterThan(0);
+
+    // Check structure of first process
+    const proc = processes[0];
+    expect(proc).toHaveProperty('pid');
+    expect(proc).toHaveProperty('name');
+    expect(proc).toHaveProperty('cpu');
+    expect(proc).toHaveProperty('memory');
+  });
+});
+
+describe('Stub Observers', () => {
+  test('NotificationListener starts and stops', async () => {
+    const listener = new NotificationListener();
+
+    expect(listener.isRunning()).toBe(false);
+
+    await listener.start();
+    expect(listener.isRunning()).toBe(true);
+
+    await listener.stop();
+    expect(listener.isRunning()).toBe(false);
+  });
+
+  test('CalendarSync starts and stops', async () => {
+    const sync = new CalendarSync();
+
+    expect(sync.isRunning()).toBe(false);
+
+    await sync.start();
+    expect(sync.isRunning()).toBe(true);
+
+    await sync.stop();
+    expect(sync.isRunning()).toBe(false);
+  });
+
+  test('EmailSync starts and stops', async () => {
+    const sync = new EmailSync();
+
+    expect(sync.isRunning()).toBe(false);
+
+    await sync.start();
+    expect(sync.isRunning()).toBe(true);
+
+    await sync.stop();
+    expect(sync.isRunning()).toBe(false);
+  });
+});