@auxiora/os-bridge 1.0.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@auxiora/os-bridge",
+  "version": "1.0.0",
+  "description": "Deep OS integration: clipboard, file watching, app control, system state",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "nanoid": "^5.1.2",
+    "@auxiora/logger": "1.0.0",
+    "@auxiora/audit": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/app-controller.ts

@@ -0,0 +1,80 @@
+import type { Platform } from './types.js';
+
+export class AppController {
+  private platform: Platform;
+
+  constructor(platform: Platform) {
+    this.platform = platform;
+  }
+
+  getCommand(action: 'launch' | 'focus' | 'close' | 'list', appName?: string): string {
+    switch (this.platform) {
+      case 'darwin':
+        return this.getDarwinCommand(action, appName);
+      case 'linux':
+        return this.getLinuxCommand(action, appName);
+      case 'win32':
+        return this.getWin32Command(action, appName);
+    }
+  }
+
+  private getDarwinCommand(action: string, appName?: string): string {
+    switch (action) {
+      case 'launch':
+        return `open -a "${appName}"`;
+      case 'focus':
+        return `osascript -e 'tell app "${appName}" to activate'`;
+      case 'close':
+        return `osascript -e 'tell app "${appName}" to quit'`;
+      case 'list':
+        return 'ps aux';
+      default:
+        return '';
+    }
+  }
+
+  private getLinuxCommand(action: string, appName?: string): string {
+    switch (action) {
+      case 'launch':
+        return `xdg-open "${appName}" || ${appName}`;
+      case 'focus':
+        return `wmctrl -a "${appName}"`;
+      case 'close':
+        return `pkill -f "${appName}"`;
+      case 'list':
+        return 'ps aux';
+      default:
+        return '';
+    }
+  }
+
+  private getWin32Command(action: string, appName?: string): string {
+    switch (action) {
+      case 'launch':
+        return `start "" "${appName}"`;
+      case 'focus':
+        return `powershell -c "(New-Object -ComObject WScript.Shell).AppActivate('${appName}')"`;
+      case 'close':
+        return `taskkill /IM "${appName}" /F`;
+      case 'list':
+        return 'tasklist';
+      default:
+        return '';
+    }
+  }
+
+  async launch(appName: string): Promise<{ success: boolean; command: string }> {
+    const command = this.getCommand('launch', appName);
+    return { success: true, command };
+  }
+
+  async focus(appName: string): Promise<{ success: boolean; command: string }> {
+    const command = this.getCommand('focus', appName);
+    return { success: true, command };
+  }
+
+  async close(appName: string): Promise<{ success: boolean; command: string }> {
+    const command = this.getCommand('close', appName);
+    return { success: true, command };
+  }
+}

package/src/clipboard.ts

@@ -0,0 +1,73 @@
+import type { ClipboardEntry } from './types.js';
+
+const MAX_HISTORY = 100;
+
+type ClipboardListener = (entry: ClipboardEntry) => void;
+
+export class ClipboardMonitor {
+  private history: ClipboardEntry[] = [];
+  private listeners: ClipboardListener[] = [];
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  getContent(): ClipboardEntry {
+    if (this.history.length > 0) {
+      return this.history[this.history.length - 1]!;
+    }
+    return { content: '', type: 'text', timestamp: Date.now() };
+  }
+
+  addEntry(content: string, type: 'text' | 'image' | 'html' = 'text'): ClipboardEntry {
+    const entry: ClipboardEntry = { content, type, timestamp: Date.now() };
+    this.history.push(entry);
+    if (this.history.length > MAX_HISTORY) {
+      this.history.shift();
+    }
+    for (const listener of this.listeners) {
+      listener(entry);
+    }
+    return entry;
+  }
+
+  onchange(cb: ClipboardListener): () => void {
+    this.listeners.push(cb);
+    return () => {
+      const idx = this.listeners.indexOf(cb);
+      if (idx !== -1) {
+        this.listeners.splice(idx, 1);
+      }
+    };
+  }
+
+  startWatching(): void {
+    this.intervalId = setInterval(() => {
+      // No-op polling — actual clipboard reading would be platform-specific
+    }, 1000);
+  }
+
+  stopWatching(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  transform(content: string, op: 'uppercase' | 'lowercase' | 'trim' | 'json-format'): string {
+    switch (op) {
+      case 'uppercase':
+        return content.toUpperCase();
+      case 'lowercase':
+        return content.toLowerCase();
+      case 'trim':
+        return content.trim();
+      case 'json-format':
+        return JSON.stringify(JSON.parse(content), null, 2);
+    }
+  }
+
+  getHistory(limit?: number): ClipboardEntry[] {
+    if (limit !== undefined) {
+      return this.history.slice(-limit);
+    }
+    return [...this.history];
+  }
+}

package/src/file-watcher.ts

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import type { FileEvent, FileClassification } from './types.js';
+
+type FileEventListener = (event: FileEvent) => void;
+
+const EXTENSION_MAP: Record<string, FileClassification> = {
+  '.pdf': 'document',
+  '.doc': 'document',
+  '.docx': 'document',
+  '.txt': 'document',
+  '.md': 'document',
+  '.rtf': 'document',
+  '.jpg': 'image',
+  '.jpeg': 'image',
+  '.png': 'image',
+  '.gif': 'image',
+  '.svg': 'image',
+  '.webp': 'image',
+  '.bmp': 'image',
+  '.mp4': 'video',
+  '.avi': 'video',
+  '.mov': 'video',
+  '.mkv': 'video',
+  '.webm': 'video',
+  '.mp3': 'audio',
+  '.wav': 'audio',
+  '.flac': 'audio',
+  '.aac': 'audio',
+  '.ogg': 'audio',
+  '.ts': 'code',
+  '.js': 'code',
+  '.py': 'code',
+  '.go': 'code',
+  '.rs': 'code',
+  '.java': 'code',
+  '.c': 'code',
+  '.cpp': 'code',
+  '.h': 'code',
+  '.rb': 'code',
+  '.php': 'code',
+  '.sh': 'code',
+  '.zip': 'archive',
+  '.tar': 'archive',
+  '.gz': 'archive',
+  '.7z': 'archive',
+  '.rar': 'archive',
+  '.bz2': 'archive',
+  '.xls': 'spreadsheet',
+  '.xlsx': 'spreadsheet',
+  '.csv': 'spreadsheet',
+  '.ppt': 'presentation',
+  '.pptx': 'presentation',
+  '.key': 'presentation',
+};
+
+export class FileWatcher {
+  private directories: string[];
+  private listeners: FileEventListener[] = [];
+  private watching = false;
+
+  constructor(config: { directories: string[] }) {
+    this.directories = config.directories;
+  }
+
+  watch(): void {
+    this.watching = true;
+  }
+
+  stop(): void {
+    this.watching = false;
+  }
+
+  onEvent(cb: FileEventListener): () => void {
+    this.listeners.push(cb);
+    return () => {
+      const idx = this.listeners.indexOf(cb);
+      if (idx !== -1) {
+        this.listeners.splice(idx, 1);
+      }
+    };
+  }
+
+  emitEvent(event: FileEvent): void {
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+
+  classifyFile(filePath: string): FileClassification {
+    const ext = path.extname(filePath).toLowerCase();
+    return EXTENSION_MAP[ext] ?? 'other';
+  }
+
+  suggestDestination(filePath: string, baseDir?: string): { classification: FileClassification; suggestedDir: string } {
+    const classification = this.classifyFile(filePath);
+    const base = baseDir || '~/Documents';
+    return {
+      classification,
+      suggestedDir: `${base}/${classification}s/`,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  Platform,
+  ClipboardEntry,
+  FileEvent,
+  FileClassification,
+  AppInfo,
+  SystemState,
+  OsBridgeConfig,
+} from './types.js';
+export { ClipboardMonitor } from './clipboard.js';
+export { FileWatcher } from './file-watcher.js';
+export { AppController } from './app-controller.js';
+export { SystemStateMonitor } from './system-state.js';

package/src/system-state.ts

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import type { Platform, SystemState } from './types.js';
+
+export class SystemStateMonitor {
+  private platform: Platform;
+
+  constructor(platform?: Platform) {
+    this.platform = platform ?? (os.platform() as Platform);
+  }
+
+  getState(): SystemState {
+    return {
+      platform: this.platform,
+      hostname: os.hostname(),
+      uptime: os.uptime(),
+      memory: this.getMemoryUsage(),
+      cpu: this.getCpuInfo(),
+    };
+  }
+
+  getMemoryUsage(): { total: number; free: number; usedPercent: number } {
+    const total = os.totalmem();
+    const free = os.freemem();
+    const usedPercent = ((total - free) / total) * 100;
+    return { total, free, usedPercent };
+  }
+
+  getCpuInfo(): { model: string; cores: number; loadAvg: number[] } {
+    const cpus = os.cpus();
+    return {
+      model: cpus[0]?.model ?? 'unknown',
+      cores: cpus.length,
+      loadAvg: os.loadavg(),
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export type Platform = 'darwin' | 'linux' | 'win32';
+
+export interface ClipboardEntry {
+  content: string;
+  type: 'text' | 'image' | 'html';
+  timestamp: number;
+}
+
+export interface FileEvent {
+  type: 'created' | 'modified' | 'deleted';
+  path: string;
+  filename: string;
+  timestamp: number;
+}
+
+export type FileClassification =
+  | 'document'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'code'
+  | 'archive'
+  | 'spreadsheet'
+  | 'presentation'
+  | 'other';
+
+export interface AppInfo {
+  name: string;
+  pid: number;
+  focused: boolean;
+}
+
+export interface SystemState {
+  platform: Platform;
+  hostname: string;
+  uptime: number;
+  memory: {
+    total: number;
+    free: number;
+    usedPercent: number;
+  };
+  cpu: {
+    model: string;
+    cores: number;
+    loadAvg: number[];
+  };
+  disk?: {
+    total: number;
+    free: number;
+    usedPercent: number;
+  };
+  battery?: {
+    level: number;
+    charging: boolean;
+  } | null;
+}
+
+export interface OsBridgeConfig {
+  watchDirs?: string[];
+  clipboardPollMs?: number;
+  platform?: Platform;
+}

package/tests/app-controller.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { AppController } from '../src/app-controller.js';
+
+describe('AppController', () => {
+  it('darwin launch command correct', () => {
+    const ctrl = new AppController('darwin');
+    expect(ctrl.getCommand('launch', 'Safari')).toBe('open -a "Safari"');
+  });
+
+  it('linux launch command correct', () => {
+    const ctrl = new AppController('linux');
+    expect(ctrl.getCommand('launch', 'firefox')).toBe('xdg-open "firefox" || firefox');
+  });
+
+  it('win32 launch command correct', () => {
+    const ctrl = new AppController('win32');
+    expect(ctrl.getCommand('launch', 'notepad')).toBe('start "" "notepad"');
+  });
+
+  it('darwin close command uses osascript', () => {
+    const ctrl = new AppController('darwin');
+    const cmd = ctrl.getCommand('close', 'Safari');
+    expect(cmd).toContain('osascript');
+    expect(cmd).toContain('quit');
+  });
+
+  it('linux close command uses pkill', () => {
+    const ctrl = new AppController('linux');
+    const cmd = ctrl.getCommand('close', 'firefox');
+    expect(cmd).toContain('pkill');
+  });
+
+  it('win32 close command uses taskkill', () => {
+    const ctrl = new AppController('win32');
+    const cmd = ctrl.getCommand('close', 'notepad');
+    expect(cmd).toContain('taskkill');
+  });
+
+  it('getCommand returns string for all actions', () => {
+    const ctrl = new AppController('darwin');
+    const actions = ['launch', 'focus', 'close', 'list'] as const;
+    for (const action of actions) {
+      const cmd = ctrl.getCommand(action, 'App');
+      expect(typeof cmd).toBe('string');
+      expect(cmd.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('launch returns command without executing', async () => {
+    const ctrl = new AppController('linux');
+    const result = await ctrl.launch('firefox');
+    expect(result.success).toBe(true);
+    expect(result.command).toBe('xdg-open "firefox" || firefox');
+  });
+
+  it('focus returns command without executing', async () => {
+    const ctrl = new AppController('darwin');
+    const result = await ctrl.focus('Safari');
+    expect(result.success).toBe(true);
+    expect(result.command).toContain('activate');
+  });
+
+  it('close returns command without executing', async () => {
+    const ctrl = new AppController('win32');
+    const result = await ctrl.close('notepad');
+    expect(result.success).toBe(true);
+    expect(result.command).toContain('taskkill');
+  });
+});

package/tests/clipboard.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ClipboardMonitor } from '../src/clipboard.js';
+
+describe('ClipboardMonitor', () => {
+  it('addEntry adds to history', () => {
+    const monitor = new ClipboardMonitor();
+    monitor.addEntry('hello');
+    expect(monitor.getHistory()).toHaveLength(1);
+    expect(monitor.getHistory()[0]!.content).toBe('hello');
+  });
+
+  it('getContent returns latest entry', () => {
+    const monitor = new ClipboardMonitor();
+    monitor.addEntry('first');
+    monitor.addEntry('second');
+    expect(monitor.getContent().content).toBe('second');
+  });
+
+  it('getContent returns empty entry when no history', () => {
+    const monitor = new ClipboardMonitor();
+    const entry = monitor.getContent();
+    expect(entry.content).toBe('');
+    expect(entry.type).toBe('text');
+  });
+
+  it('getHistory returns limited entries', () => {
+    const monitor = new ClipboardMonitor();
+    monitor.addEntry('a');
+    monitor.addEntry('b');
+    monitor.addEntry('c');
+    const limited = monitor.getHistory(2);
+    expect(limited).toHaveLength(2);
+    expect(limited[0]!.content).toBe('b');
+    expect(limited[1]!.content).toBe('c');
+  });
+
+  it('transform uppercase works', () => {
+    const monitor = new ClipboardMonitor();
+    expect(monitor.transform('hello', 'uppercase')).toBe('HELLO');
+  });
+
+  it('transform lowercase works', () => {
+    const monitor = new ClipboardMonitor();
+    expect(monitor.transform('HELLO', 'lowercase')).toBe('hello');
+  });
+
+  it('transform trim works', () => {
+    const monitor = new ClipboardMonitor();
+    expect(monitor.transform('  hello  ', 'trim')).toBe('hello');
+  });
+
+  it('transform json-format pretty-prints JSON', () => {
+    const monitor = new ClipboardMonitor();
+    const result = monitor.transform('{"a":1}', 'json-format');
+    expect(result).toBe('{\n  "a": 1\n}');
+  });
+
+  it('onchange listener fires on addEntry', () => {
+    const monitor = new ClipboardMonitor();
+    const listener = vi.fn();
+    monitor.onchange(listener);
+    monitor.addEntry('test');
+    expect(listener).toHaveBeenCalledOnce();
+    expect(listener.mock.calls[0]![0]!.content).toBe('test');
+  });
+
+  it('onchange unsubscribe stops notifications', () => {
+    const monitor = new ClipboardMonitor();
+    const listener = vi.fn();
+    const unsub = monitor.onchange(listener);
+    unsub();
+    monitor.addEntry('test');
+    expect(listener).not.toHaveBeenCalled();
+  });
+});

package/tests/file-watcher.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi } from 'vitest';
+import { FileWatcher } from '../src/file-watcher.js';
+
+describe('FileWatcher', () => {
+  it('classifyFile: .pdf returns document', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('report.pdf')).toBe('document');
+  });
+
+  it('classifyFile: .jpg returns image', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('photo.jpg')).toBe('image');
+  });
+
+  it('classifyFile: .mp4 returns video', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('clip.mp4')).toBe('video');
+  });
+
+  it('classifyFile: .mp3 returns audio', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('song.mp3')).toBe('audio');
+  });
+
+  it('classifyFile: .ts returns code', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('index.ts')).toBe('code');
+  });
+
+  it('classifyFile: .zip returns archive', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('backup.zip')).toBe('archive');
+  });
+
+  it('classifyFile: .xlsx returns spreadsheet', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('data.xlsx')).toBe('spreadsheet');
+  });
+
+  it('classifyFile: .pptx returns presentation', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('slides.pptx')).toBe('presentation');
+  });
+
+  it('classifyFile: unknown ext returns other', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    expect(watcher.classifyFile('data.xyz')).toBe('other');
+  });
+
+  it('suggestDestination returns correct dir', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    const result = watcher.suggestDestination('photo.png');
+    expect(result.classification).toBe('image');
+    expect(result.suggestedDir).toBe('~/Documents/images/');
+  });
+
+  it('suggestDestination uses custom baseDir', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    const result = watcher.suggestDestination('report.pdf', '/home/user');
+    expect(result.suggestedDir).toBe('/home/user/documents/');
+  });
+
+  it('emitEvent notifies listener', () => {
+    const watcher = new FileWatcher({ directories: ['/tmp'] });
+    const listener = vi.fn();
+    watcher.onEvent(listener);
+    const event = { type: 'created' as const, path: '/tmp/test.txt', filename: 'test.txt', timestamp: Date.now() };
+    watcher.emitEvent(event);
+    expect(listener).toHaveBeenCalledWith(event);
+  });
+
+  it('onEvent unsubscribe stops notifications', () => {
+    const watcher = new FileWatcher({ directories: [] });
+    const listener = vi.fn();
+    const unsub = watcher.onEvent(listener);
+    unsub();
+    watcher.emitEvent({ type: 'created', path: '/tmp/a.txt', filename: 'a.txt', timestamp: Date.now() });
+    expect(listener).not.toHaveBeenCalled();
+  });
+});

package/tests/system-state.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { SystemStateMonitor } from '../src/system-state.js';
+
+describe('SystemStateMonitor', () => {
+  it('getState returns valid platform', () => {
+    const monitor = new SystemStateMonitor();
+    const state = monitor.getState();
+    expect(['darwin', 'linux', 'win32']).toContain(state.platform);
+  });
+
+  it('getState returns hostname', () => {
+    const monitor = new SystemStateMonitor();
+    const state = monitor.getState();
+    expect(typeof state.hostname).toBe('string');
+    expect(state.hostname.length).toBeGreaterThan(0);
+  });
+
+  it('getState returns uptime > 0', () => {
+    const monitor = new SystemStateMonitor();
+    const state = monitor.getState();
+    expect(state.uptime).toBeGreaterThan(0);
+  });
+
+  it('getMemoryUsage returns valid percentages', () => {
+    const monitor = new SystemStateMonitor();
+    const mem = monitor.getMemoryUsage();
+    expect(mem.total).toBeGreaterThan(0);
+    expect(mem.free).toBeGreaterThan(0);
+    expect(mem.usedPercent).toBeGreaterThan(0);
+    expect(mem.usedPercent).toBeLessThan(100);
+  });
+
+  it('getCpuInfo returns model and cores', () => {
+    const monitor = new SystemStateMonitor();
+    const cpu = monitor.getCpuInfo();
+    expect(typeof cpu.model).toBe('string');
+    expect(cpu.model.length).toBeGreaterThan(0);
+    expect(cpu.cores).toBeGreaterThan(0);
+  });
+
+  it('getCpuInfo cores > 0', () => {
+    const monitor = new SystemStateMonitor();
+    const cpu = monitor.getCpuInfo();
+    expect(cpu.cores).toBeGreaterThan(0);
+  });
+
+  it('getCpuInfo loadAvg is an array', () => {
+    const monitor = new SystemStateMonitor();
+    const cpu = monitor.getCpuInfo();
+    expect(Array.isArray(cpu.loadAvg)).toBe(true);
+    expect(cpu.loadAvg.length).toBe(3);
+  });
+
+  it('constructor accepts explicit platform', () => {
+    const monitor = new SystemStateMonitor('darwin');
+    const state = monitor.getState();
+    expect(state.platform).toBe('darwin');
+  });
+});