lightman-agent 1.0.0

package/src/services/powerScheduler.ts

@@ -0,0 +1,260 @@
+import { execFile } from 'child_process';
+import { getPlatform } from '../lib/platform.js';
+import type { PowerScheduleConfig } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+import type { WsClient } from './websocket.js';
+
+/**
+ * PowerScheduler — handles local cron-based shutdown and server-pushed power commands.
+ *
+ * Shutdown flow:
+ * 1. Every minute, check if current time matches shutdownCron
+ * 2. If match: send warning to server, wait shutdownWarningSeconds, then shut down
+ * 3. Also listens for server-pushed "system:shutdown" via the command executor (separate)
+ *
+ * The server can also override/update the schedule at runtime via WebSocket.
+ */
+export class PowerScheduler {
+  private config: PowerScheduleConfig;
+  private logger: Logger;
+  private wsClient: WsClient;
+  private timer: NodeJS.Timeout | null = null;
+  private shutdownPending = false;
+  private shutdownTimer: NodeJS.Timeout | null = null;
+
+  constructor(config: PowerScheduleConfig, logger: Logger, wsClient: WsClient) {
+    this.config = config;
+    this.logger = logger;
+    this.wsClient = wsClient;
+  }
+
+  start(): void {
+    if (!this.config.shutdownCron) {
+      this.logger.info('PowerScheduler: no shutdownCron configured, skipping');
+      return;
+    }
+
+    this.logger.info(
+      `PowerScheduler started (shutdown: "${this.config.shutdownCron}", tz: ${this.config.timezone})`
+    );
+
+    // Check every 30 seconds (cron resolution is 1 minute, but we check more often to not miss)
+    this.timer = setInterval(() => {
+      this.checkSchedule();
+    }, 30_000);
+
+    // Also check immediately
+    this.checkSchedule();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.shutdownTimer) {
+      clearTimeout(this.shutdownTimer);
+      this.shutdownTimer = null;
+    }
+    this.shutdownPending = false;
+    this.logger.info('PowerScheduler stopped');
+  }
+
+  /**
+   * Update the schedule at runtime (e.g., from server push).
+   */
+  updateSchedule(newConfig: Partial<PowerScheduleConfig>): void {
+    if (newConfig.shutdownCron !== undefined) {
+      this.config.shutdownCron = newConfig.shutdownCron;
+    }
+    if (newConfig.startupCron !== undefined) {
+      this.config.startupCron = newConfig.startupCron;
+    }
+    if (newConfig.timezone !== undefined) {
+      this.config.timezone = newConfig.timezone;
+    }
+    if (newConfig.shutdownWarningSeconds !== undefined) {
+      this.config.shutdownWarningSeconds = newConfig.shutdownWarningSeconds;
+    }
+    this.logger.info(`PowerScheduler schedule updated: shutdown="${this.config.shutdownCron}"`);
+  }
+
+  /**
+   * Trigger shutdown immediately (called by server command or local schedule).
+   */
+  triggerShutdown(reason: string): void {
+    if (this.shutdownPending) {
+      this.logger.info('Shutdown already pending, ignoring duplicate trigger');
+      return;
+    }
+
+    this.shutdownPending = true;
+    const warningSeconds = this.config.shutdownWarningSeconds ?? 60;
+
+    this.logger.warn(`Shutdown triggered (${reason}), warning period: ${warningSeconds}s`);
+
+    // Notify server that shutdown is imminent
+    this.wsClient.send({
+      type: 'agent:shutdown-warning',
+      payload: {
+        reason,
+        shutdownInSeconds: warningSeconds,
+      },
+      timestamp: Date.now(),
+    });
+
+    this.shutdownTimer = setTimeout(() => {
+      this.executeShutdown(reason);
+    }, warningSeconds * 1_000);
+  }
+
+  /**
+   * Cancel a pending scheduled shutdown.
+   */
+  cancelShutdown(): boolean {
+    if (!this.shutdownPending || !this.shutdownTimer) {
+      return false;
+    }
+    clearTimeout(this.shutdownTimer);
+    this.shutdownTimer = null;
+    this.shutdownPending = false;
+
+    this.logger.info('Scheduled shutdown cancelled');
+    this.wsClient.send({
+      type: 'agent:shutdown-cancelled',
+      payload: {},
+      timestamp: Date.now(),
+    });
+    return true;
+  }
+
+  isShutdownPending(): boolean {
+    return this.shutdownPending;
+  }
+
+  // --- Private ---
+
+  private checkSchedule(): void {
+    if (!this.config.shutdownCron || this.shutdownPending) return;
+
+    const now = this.getNowInTimezone();
+    if (this.matchesCron(this.config.shutdownCron, now)) {
+      this.triggerShutdown('local-schedule');
+    }
+  }
+
+  private executeShutdown(reason: string): void {
+    this.logger.warn(`Executing system shutdown (reason: ${reason})`);
+
+    // Notify server before going down
+    this.wsClient.send({
+      type: 'agent:shutting-down',
+      payload: { reason },
+      timestamp: Date.now(),
+    });
+
+    const platform = getPlatform();
+    let bin: string;
+    let args: string[];
+
+    switch (platform) {
+      case 'windows':
+        bin = 'shutdown';
+        args = ['/s', '/t', '5', '/c', `LIGHTMAN scheduled shutdown: ${reason}`];
+        break;
+      case 'darwin':
+        bin = 'shutdown';
+        args = ['-h', '+1'];
+        break;
+      default:
+        bin = 'shutdown';
+        args = ['-h', 'now'];
+    }
+
+    // Give WS message time to send, then shut down
+    setTimeout(() => {
+      execFile(bin, args, (err) => {
+        if (err) {
+          this.logger.error('Shutdown exec failed:', err.message);
+          this.shutdownPending = false;
+        }
+      });
+    }, 2_000);
+  }
+
+  /**
+   * Get current date/time components in the configured timezone.
+   */
+  private getNowInTimezone(): { minute: number; hour: number; dayOfMonth: number; month: number; dayOfWeek: number } {
+    const tz = this.config.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const now = new Date();
+
+    // Use Intl to get components in the target timezone
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      hour: 'numeric',
+      minute: 'numeric',
+      day: 'numeric',
+      month: 'numeric',
+      weekday: 'short',
+      hour12: false,
+    }).formatToParts(now);
+
+    const get = (type: string) => {
+      const part = parts.find((p) => p.type === type);
+      return part ? parseInt(part.value, 10) : 0;
+    };
+
+    const weekdayStr = parts.find((p) => p.type === 'weekday')?.value || '';
+    const dayOfWeekMap: Record<string, number> = {
+      Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6,
+    };
+
+    return {
+      minute: get('minute'),
+      hour: get('hour'),
+      dayOfMonth: get('day'),
+      month: get('month'),
+      dayOfWeek: dayOfWeekMap[weekdayStr] ?? 0,
+    };
+  }
+
+  /**
+   * Simple 5-field cron matcher: minute hour dayOfMonth month dayOfWeek
+   * Supports: *, numbers, ranges (1-5), steps (asterisk/5), lists (1,3,5)
+   */
+  private matchesCron(
+    expr: string,
+    now: { minute: number; hour: number; dayOfMonth: number; month: number; dayOfWeek: number }
+  ): boolean {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) return false;
+
+    const values = [now.minute, now.hour, now.dayOfMonth, now.month, now.dayOfWeek];
+
+    return fields.every((field, i) => this.matchesCronField(field, values[i]));
+  }
+
+  private matchesCronField(field: string, value: number): boolean {
+    // Handle list: "1,3,5"
+    const parts = field.split(',');
+    return parts.some((part) => {
+      // Handle step: "*/5" or "1-10/2"
+      const [rangeOrWild, stepStr] = part.split('/');
+      const step = stepStr ? parseInt(stepStr, 10) : 1;
+
+      if (rangeOrWild === '*') {
+        return value % step === 0;
+      }
+
+      // Handle range: "1-5"
+      if (rangeOrWild.includes('-')) {
+        const [lo, hi] = rangeOrWild.split('-').map(Number);
+        return value >= lo && value <= hi && (value - lo) % step === 0;
+      }
+
+      // Single value
+      return parseInt(rangeOrWild, 10) === value;
+    });
+  }
+}

package/src/services/provisioning.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { AgentConfig, Identity } from '../lib/types.js';
+import { readIdentity, writeIdentity } from '../lib/identity.js';
+import type { Logger } from '../lib/logger.js';
+
+const provisionResponseSchema = z.object({
+  deviceId: z.string().uuid(),
+  apiKey: z.string().min(1),
+});
+
+interface ProvisionResult {
+  identity: Identity;
+  fromCache: boolean;
+}
+
+/**
+ * Provision the agent: check for cached identity, otherwise call CMS provisioning endpoints.
+ * If pairing is required, polls until admin approves (with timeout).
+ */
+export async function provision(
+  config: AgentConfig,
+  logger: Logger
+): Promise<ProvisionResult> {
+  // Check for cached identity first
+  const cached = readIdentity(config.identityFile);
+  if (cached) {
+    logger.info('Using cached identity', { deviceId: cached.deviceId });
+    return { identity: cached, fromCache: true };
+  }
+
+  logger.info(`Provisioning device: ${config.deviceSlug}`);
+
+  const baseUrl = `${config.serverUrl}/api/devices/provision/${encodeURIComponent(config.deviceSlug)}`;
+
+  // Step 1: Request provisioning
+  const res = await fetch(baseUrl);
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Provision request failed (${res.status}): ${body}`);
+  }
+
+  const data = await res.json() as Record<string, unknown>;
+
+  // Auto-provisioned (IP match)
+  if (data.deviceId && data.apiKey) {
+    const parsed = provisionResponseSchema.safeParse(data);
+    if (!parsed.success) {
+      throw new Error('Invalid provision response: ' + parsed.error.message);
+    }
+    const identity: Identity = {
+      deviceId: parsed.data.deviceId,
+      apiKey: parsed.data.apiKey,
+    };
+    writeIdentity(config.identityFile, identity);
+    logger.info('Auto-provisioned', { deviceId: identity.deviceId });
+    return { identity, fromCache: false };
+  }
+
+  // Pairing required — display code and poll
+  if (data.requiresPairing && data.code) {
+    const code = data.code as string;
+    logger.warn(`Pairing required. Enter code in admin UI: ${code}`);
+    logger.info('Waiting for admin to approve pairing...');
+
+    const identity = await pollForPairing(
+      `${baseUrl}/status?code=${encodeURIComponent(code)}`,
+      logger
+    );
+
+    writeIdentity(config.identityFile, identity);
+    logger.info('Pairing complete', { deviceId: identity.deviceId });
+    return { identity, fromCache: false };
+  }
+
+  throw new Error('Unexpected provision response: ' + JSON.stringify(data));
+}
+
+async function pollForPairing(
+  statusUrl: string,
+  logger: Logger,
+  timeoutMs = 600_000,
+  intervalMs = 5_000
+): Promise<Identity> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+
+    try {
+      const res = await fetch(statusUrl);
+      if (!res.ok) {
+        logger.warn(`Pairing poll failed (${res.status}), retrying...`);
+        continue;
+      }
+
+      const data = await res.json() as Record<string, unknown>;
+
+      if (data.deviceId && data.apiKey) {
+        const parsed = provisionResponseSchema.safeParse(data);
+        if (!parsed.success) {
+          throw new Error('Invalid pairing response: ' + parsed.error.message);
+        }
+        return {
+          deviceId: parsed.data.deviceId,
+          apiKey: parsed.data.apiKey,
+        };
+      }
+
+      logger.debug('Pairing not yet complete, polling again...');
+    } catch (err) {
+      logger.warn('Pairing poll error, retrying...', err);
+    }
+  }
+
+  throw new Error('Pairing timed out after ' + (timeoutMs / 1000) + 's');
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/services/serialBridge.ts

@@ -0,0 +1,230 @@
+import { execSync, spawn, type ChildProcess } from 'child_process';
+import { platform } from 'os';
+import { createReadStream } from 'fs';
+import type { WsClient } from './websocket.js';
+import type { Logger } from '../lib/logger.js';
+
+/**
+ * SerialBridge — reads raw characters from a COM/serial port and converts them
+ * to hardware events (monophone:pickup, monophone:hangup, button:press).
+ *
+ * Character mapping:
+ *   * (asterisk)  → monophone:pickup   (handset lifted)
+ *   # (hash)      → monophone:hangup   (handset replaced)
+ *   1-9           → button:press with buttonId 1-9
+ *
+ * Events are forwarded to the server via WebSocket as `serial-bridge:event`.
+ * The server then publishes them to MQTT so the display app receives them.
+ *
+ * Uses PowerShell on Windows / raw file read on Linux — NO native npm dependencies.
+ */
+export class SerialBridge {
+  private wsClient: WsClient;
+  private logger: Logger;
+  private port: string;
+  private baudRate: number;
+  private controllerId: string;
+  private running = false;
+  private reader: ReturnType<typeof setInterval> | null = null;
+  private buffer = '';
+  private onEvent?: (event: Record<string, unknown>) => void;
+
+  // Windows-specific: PowerShell process for reading serial
+  private psProcess: ChildProcess | null = null;
+
+  constructor(opts: {
+    wsClient: WsClient;
+    logger: Logger;
+    port: string;
+    baudRate?: number;
+    controllerId: string;
+    onEvent?: (event: Record<string, unknown>) => void;
+  }) {
+    this.wsClient = opts.wsClient;
+    this.logger = opts.logger;
+    this.port = opts.port;
+    this.baudRate = opts.baudRate || 115200;
+    this.controllerId = opts.controllerId;
+    this.onEvent = opts.onEvent;
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+
+    this.logger.info(`Serial bridge starting: ${this.port} @ ${this.baudRate} baud → controllerId: ${this.controllerId}`);
+
+    const os = platform();
+    if (os === 'win32') {
+      this.startWindows();
+    } else {
+      this.startLinux();
+    }
+  }
+
+  stop(): void {
+    this.running = false;
+
+    if (this.psProcess) {
+      try { this.psProcess.kill(); } catch { /* ignore */ }
+      this.psProcess = null;
+    }
+
+    if (this.reader) {
+      clearInterval(this.reader);
+      this.reader = null;
+    }
+
+    this.logger.info(`Serial bridge stopped: ${this.port}`);
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Windows: Use PowerShell to open the COM port and stream data line by line.
+   * This avoids needing the `serialport` npm package.
+   */
+  private startWindows(): void {
+    // PowerShell script that opens COM port and writes each received char to stdout
+    const psScript = `
+$port = New-Object System.IO.Ports.SerialPort '${this.port}', ${this.baudRate}, 'None', 8, 'One'
+$port.ReadTimeout = 1000
+$port.DtrEnable = $true
+$port.RtsEnable = $true
+try {
+  $port.Open()
+  [Console]::Out.WriteLine("SERIAL_BRIDGE_READY")
+  while ($true) {
+    try {
+      $char = [char]$port.ReadChar()
+      [Console]::Out.Write($char)
+      [Console]::Out.Flush()
+    } catch [System.TimeoutException] {
+      # Read timeout, just loop
+    }
+  }
+} catch {
+  [Console]::Error.WriteLine("SERIAL_ERROR: $_")
+} finally {
+  if ($port.IsOpen) { $port.Close() }
+}
+`;
+
+    this.psProcess = spawn('powershell', [
+      '-NoProfile', '-NonInteractive', '-Command', psScript,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+
+    this.psProcess.stdout?.on('data', (data: Buffer) => {
+      const text = data.toString();
+
+      // Check for ready signal
+      if (text.includes('SERIAL_BRIDGE_READY')) {
+        this.logger.info(`Serial bridge connected to ${this.port}`);
+        // Remove the ready signal from the text before processing
+        const cleaned = text.replace('SERIAL_BRIDGE_READY', '').replace(/[\r\n]/g, '');
+        if (cleaned) this.processChars(cleaned);
+        return;
+      }
+
+      this.processChars(text);
+    });
+
+    this.psProcess.stderr?.on('data', (data: Buffer) => {
+      const msg = data.toString().trim();
+      if (msg) {
+        this.logger.error(`Serial bridge error: ${msg}`);
+      }
+    });
+
+    this.psProcess.on('exit', (code: number | null) => {
+      this.logger.warn(`Serial bridge PowerShell exited with code ${code}`);
+      if (this.running) {
+        // Auto-restart after 3 seconds
+        this.logger.info('Serial bridge will restart in 3s...');
+        setTimeout(() => {
+          if (this.running) this.startWindows();
+        }, 3000);
+      }
+    });
+  }
+
+  /**
+   * Linux: Read directly from /dev/ttyUSBx or /dev/ttyACMx.
+   * Configure baud rate with stty first.
+   */
+  private startLinux(): void {
+    try {
+      execSync(`stty -F ${this.port} ${this.baudRate} raw -echo`, { timeout: 5000 });
+    } catch (err) {
+      this.logger.error(`Failed to configure serial port ${this.port}:`, err);
+      return;
+    }
+
+    this.logger.info(`Serial bridge connected to ${this.port}`);
+
+    const stream = createReadStream(this.port, { encoding: 'utf-8' });
+
+    stream.on('data', (chunk: string | Buffer) => {
+      this.processChars(typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
+    });
+
+    stream.on('error', (err: Error) => {
+      this.logger.error(`Serial bridge read error: ${err.message}`);
+      if (this.running) {
+        this.logger.info('Serial bridge will restart in 3s...');
+        setTimeout(() => {
+          if (this.running) this.startLinux();
+        }, 3000);
+      }
+    });
+
+    stream.on('close', () => {
+      this.logger.warn('Serial bridge stream closed');
+    });
+  }
+
+  /**
+   * Process received characters and emit hardware events.
+   *
+   *   *  → monophone:pickup
+   *   #  → monophone:hangup
+   *   1-9 → button:press (buttonId = digit)
+   */
+  private processChars(text: string): void {
+    for (const char of text) {
+      if (char === '*') {
+        this.emitEvent('monophone:pickup');
+      } else if (char === '#') {
+        this.emitEvent('monophone:hangup');
+      } else if (char >= '1' && char <= '9') {
+        this.emitEvent('button:press', parseInt(char, 10));
+      }
+      // Ignore all other characters (newlines, spaces, noise)
+    }
+  }
+
+  private emitEvent(type: string, buttonId?: number): void {
+    const event: Record<string, unknown> = {
+      type,
+      controllerId: this.controllerId,
+      timestamp: Date.now(),
+    };
+    if (buttonId !== undefined) {
+      event.buttonId = buttonId;
+    }
+
+    this.logger.info(`Serial bridge event: ${type}${buttonId !== undefined ? ` buttonId=${buttonId}` : ''} (${this.port} → ${this.controllerId})`);
+
+    // Send to server (for admin UI, MQTT, etc.)
+    this.wsClient.send({
+      type: 'serial-bridge:event',
+      payload: event,
+      timestamp: Date.now(),
+    });
+
+    // Broadcast locally to Chrome display directly
+    this.onEvent?.(event);
+  }
+}