lightman-agent 1.0.0

package/src/lib/config.ts

@@ -0,0 +1,69 @@
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { z } from 'zod';
+import type { AgentConfig } from './types.js';
+
+const kioskSchema = z.object({
+  browserPath: z.string().default('chromium-browser'),
+  defaultUrl: z.string().url().default('http://localhost:3401/display'),
+  extraArgs: z.array(z.string()).default([]),
+  pollIntervalMs: z.number().int().min(1000).default(10_000),
+  maxCrashesInWindow: z.number().int().min(1).default(10),
+  crashWindowMs: z.number().int().min(10_000).default(300_000),
+  shellMode: z.boolean().default(false),
+});
+
+const screenshotSchema = z.object({
+  captureCommand: z.string().default('scrot'),
+  quality: z.number().int().min(1).max(100).default(80),
+  uploadEndpoint: z.string().default('/api/devices/{deviceId}/screenshot'),
+});
+
+const powerScheduleSchema = z.object({
+  shutdownCron: z.string().optional(),
+  startupCron: z.string().optional(),
+  timezone: z.string().default(Intl.DateTimeFormat().resolvedOptions().timeZone),
+  shutdownWarningSeconds: z.number().int().min(0).max(600).default(60),
+});
+
+const configSchema = z.object({
+  serverUrl: z.string().url(),
+  deviceSlug: z.string().min(1),
+  healthIntervalMs: z.number().int().min(5000).default(60000),
+  logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  logFile: z.string().default('agent.log'),
+  identityFile: z.string().default('.lightman-identity.json'),
+  localServices: z.boolean().default(true),
+  kiosk: kioskSchema.optional(),
+  screenshot: screenshotSchema.optional(),
+  powerSchedule: powerScheduleSchema.optional(),
+});
+
+export function loadConfig(configPath?: string): AgentConfig {
+  const filePath = configPath || resolve(process.cwd(), 'agent.config.json');
+
+  if (!existsSync(filePath)) {
+    throw new Error(`Config file not found: ${filePath}`);
+  }
+
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Invalid JSON in config file ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Apply environment overrides
+  const merged = {
+    ...raw,
+    ...(process.env.LIGHTMAN_SERVER_URL && { serverUrl: process.env.LIGHTMAN_SERVER_URL }),
+    ...(process.env.LIGHTMAN_DEVICE_SLUG && { deviceSlug: process.env.LIGHTMAN_DEVICE_SLUG }),
+    ...(process.env.LIGHTMAN_HEALTH_INTERVAL && { healthIntervalMs: parseInt(process.env.LIGHTMAN_HEALTH_INTERVAL, 10) }),
+    ...(process.env.LIGHTMAN_LOG_LEVEL && { logLevel: process.env.LIGHTMAN_LOG_LEVEL }),
+    ...(process.env.LIGHTMAN_LOG_FILE && { logFile: process.env.LIGHTMAN_LOG_FILE }),
+    ...(process.env.LIGHTMAN_IDENTITY_FILE && { identityFile: process.env.LIGHTMAN_IDENTITY_FILE }),
+  };
+
+  const result = configSchema.parse(merged);
+  return result as AgentConfig;
+}

package/src/lib/identity.ts

@@ -0,0 +1,40 @@
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { mkdirSync } from 'fs';
+import type { Identity } from './types.js';
+
+export function readIdentity(filePath: string): Identity | null {
+  const fullPath = resolve(process.cwd(), filePath);
+
+  if (!existsSync(fullPath)) {
+    return null;
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(fullPath, 'utf-8'));
+    if (raw.deviceId && raw.apiKey) {
+      return { deviceId: raw.deviceId, apiKey: raw.apiKey };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeIdentity(filePath: string, identity: Identity): void {
+  const fullPath = resolve(process.cwd(), filePath);
+  const dir = dirname(fullPath);
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(fullPath, JSON.stringify(identity, null, 2), { mode: 0o600 });
+
+  // Ensure permissions are correct even if file already existed
+  try {
+    chmodSync(fullPath, 0o600);
+  } catch {
+    // Ignore permission errors on Windows
+  }
+}

package/src/lib/logger.ts

@@ -0,0 +1,137 @@
+import { appendFileSync, existsSync, mkdirSync, statSync, renameSync, unlinkSync } from 'fs';
+import { dirname } from 'path';
+import type { LogEntry } from './types.js';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_LABELS: Record<LogLevel, string> = {
+  debug: 'DEBUG',
+  info: 'INFO ',
+  warn: 'WARN ',
+  error: 'ERROR',
+};
+
+const MAX_LOG_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_ROTATED_FILES = 3; // Keep agent.log.1, .2, .3
+
+export class Logger {
+  private level: LogLevel;
+  private logFile: string | null;
+  private listeners: Array<(entry: LogEntry) => void> = [];
+  private writesSinceRotateCheck = 0;
+
+  constructor(level: LogLevel = 'info', logFile?: string) {
+    this.level = level;
+    this.logFile = logFile || null;
+
+    if (this.logFile) {
+      const dir = dirname(this.logFile);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  onLog(fn: (entry: LogEntry) => void): void {
+    this.listeners = [...this.listeners, fn];
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    this.log('debug', message, ...args);
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    this.log('info', message, ...args);
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    this.log('warn', message, ...args);
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    this.log('error', message, ...args);
+  }
+
+  private log(level: LogLevel, message: string, ...args: unknown[]): void {
+    if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level]) {
+      return;
+    }
+
+    const timestamp = new Date().toISOString();
+    const label = LEVEL_LABELS[level];
+    const formatted = `[${timestamp}] [${label}] ${message}`;
+
+    // Console output
+    if (level === 'error') {
+      console.error(formatted, ...args);
+    } else if (level === 'warn') {
+      console.warn(formatted, ...args);
+    } else {
+      console.log(formatted, ...args);
+    }
+
+    // File output (with rotation)
+    if (this.logFile) {
+      try {
+        const extra = args.length > 0 ? ' ' + args.map(a => JSON.stringify(a)).join(' ') : '';
+        appendFileSync(this.logFile, formatted + extra + '\n');
+
+        // Check rotation every 100 writes to avoid stat() on every log line
+        this.writesSinceRotateCheck++;
+        if (this.writesSinceRotateCheck >= 100) {
+          this.writesSinceRotateCheck = 0;
+          this.rotateIfNeeded();
+        }
+      } catch {
+        // Silently fail file writes to avoid recursive errors
+      }
+    }
+
+    // Notify listeners
+    const entry: LogEntry = { timestamp, level, message, source: 'agent' };
+    for (const listener of this.listeners) {
+      try {
+        listener(entry);
+      } catch {
+        // Prevent listener errors from breaking logging
+      }
+    }
+  }
+
+  private rotateIfNeeded(): void {
+    if (!this.logFile) return;
+    try {
+      const stat = statSync(this.logFile);
+      if (stat.size < MAX_LOG_SIZE_BYTES) return;
+
+      // Rotate: agent.log.3 → delete, agent.log.2 → .3, agent.log.1 → .2, agent.log → .1
+      for (let i = MAX_ROTATED_FILES; i >= 1; i--) {
+        const src = i === 1 ? this.logFile : `${this.logFile}.${i - 1}`;
+        const dst = `${this.logFile}.${i}`;
+        try {
+          if (i === MAX_ROTATED_FILES && existsSync(dst)) {
+            unlinkSync(dst);
+          }
+          if (existsSync(src)) {
+            renameSync(src, dst);
+          }
+        } catch {
+          // Best effort rotation
+        }
+      }
+    } catch {
+      // stat failed, skip rotation
+    }
+  }
+}

package/src/lib/platform.ts

@@ -0,0 +1,10 @@
+import { platform } from 'os';
+
+export type Platform = 'linux' | 'windows' | 'darwin';
+
+export function getPlatform(): Platform {
+  const p = platform();
+  if (p === 'win32') return 'windows';
+  if (p === 'darwin') return 'darwin';
+  return 'linux';
+}

package/src/lib/rpi.ts

@@ -0,0 +1,180 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, openSync, writeSync, closeSync } from 'fs';
+
+// --- RPi Detection ---
+
+let isRpiCached: boolean | null = null;
+
+/**
+ * Detect if this machine is a Raspberry Pi by checking /proc/device-tree/model.
+ */
+export function isRaspberryPi(): boolean {
+  if (isRpiCached !== null) return isRpiCached;
+  try {
+    if (!existsSync('/proc/device-tree/model')) {
+      isRpiCached = false;
+      return false;
+    }
+    const model = readFileSync('/proc/device-tree/model', 'utf-8');
+    isRpiCached = model.toLowerCase().includes('raspberry pi');
+    return isRpiCached;
+  } catch {
+    isRpiCached = false;
+    return false;
+  }
+}
+
+/** Reset detection cache (for testing). */
+export function resetRpiCache(): void {
+  isRpiCached = null;
+}
+
+// --- RPi Model Info ---
+
+export interface RpiInfo {
+  model: string | null;
+  serial: string | null;
+  revision: string | null;
+}
+
+export function getRpiInfo(): RpiInfo {
+  const info: RpiInfo = { model: null, serial: null, revision: null };
+  try {
+    info.model = readFileSync('/proc/device-tree/model', 'utf-8').replace(/\0/g, '').trim();
+  } catch { /* not available */ }
+  try {
+    const cpuinfo = readFileSync('/proc/cpuinfo', 'utf-8');
+    const serialMatch = cpuinfo.match(/Serial\s*:\s*([0-9a-fA-F]+)/);
+    if (serialMatch) info.serial = serialMatch[1];
+    const revisionMatch = cpuinfo.match(/Revision\s*:\s*([0-9a-fA-F]+)/);
+    if (revisionMatch) info.revision = revisionMatch[1];
+  } catch { /* not available */ }
+  return info;
+}
+
+// --- GPU Temperature ---
+
+/**
+ * Read GPU temperature via vcgencmd. Returns null if not available.
+ */
+export function getGpuTemp(): number | null {
+  try {
+    const output = execFileSync('vcgencmd', ['measure_temp'], {
+      timeout: 3000,
+      stdio: 'pipe',
+    }).toString();
+    // Output format: temp=42.8'C
+    const match = output.match(/temp=([\d.]+)/);
+    if (match) return Math.round(parseFloat(match[1]) * 10) / 10;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// --- Throttle Status ---
+
+/**
+ * Read throttle/undervoltage status via vcgencmd. Returns null if not available.
+ * See: https://www.raspberrypi.com/documentation/computers/os.html#get_throttled
+ *
+ * Bit meanings:
+ *  0: Under-voltage detected
+ *  1: Arm frequency capped
+ *  2: Currently throttled
+ *  3: Soft temperature limit active
+ * 16: Under-voltage has occurred
+ * 17: Arm frequency capping has occurred
+ * 18: Throttling has occurred
+ * 19: Soft temperature limit has occurred
+ */
+export function getThrottled(): number | null {
+  try {
+    const output = execFileSync('vcgencmd', ['get_throttled'], {
+      timeout: 3000,
+      stdio: 'pipe',
+    }).toString();
+    // Output format: throttled=0x0
+    const match = output.match(/throttled=(0x[0-9a-fA-F]+)/);
+    if (match) return parseInt(match[1], 16);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// --- SD Card Read-Only Check ---
+
+/**
+ * Check if the root filesystem is mounted read-only.
+ */
+export function isSdCardReadOnly(): boolean {
+  try {
+    const mounts = readFileSync('/proc/mounts', 'utf-8');
+    const rootLine = mounts.split('\n').find((line) => {
+      const parts = line.split(' ');
+      return parts[1] === '/';
+    });
+    if (!rootLine) return false;
+    const options = rootLine.split(' ')[3] || '';
+    return options.split(',').includes('ro');
+  } catch {
+    return false;
+  }
+}
+
+// --- Hardware Watchdog ---
+
+let watchdogFd: number | null = null;
+let watchdogTimer: NodeJS.Timeout | null = null;
+const WATCHDOG_DEVICE = '/dev/watchdog';
+const WATCHDOG_INTERVAL_MS = 10_000; // Pet every 10 seconds
+
+/**
+ * Start the hardware watchdog. Writes to /dev/watchdog every 10s.
+ * If the agent dies, the kernel will reboot after ~15s.
+ * Returns true if started, false if not available.
+ */
+export function startWatchdog(): boolean {
+  if (watchdogFd !== null) return true; // Already running
+  try {
+    if (!existsSync(WATCHDOG_DEVICE)) return false;
+    watchdogFd = openSync(WATCHDOG_DEVICE, 'w');
+    // Pet immediately
+    petWatchdog();
+    // Set up periodic petting
+    watchdogTimer = setInterval(petWatchdog, WATCHDOG_INTERVAL_MS);
+    return true;
+  } catch {
+    watchdogFd = null;
+    return false;
+  }
+}
+
+/**
+ * Stop the hardware watchdog gracefully.
+ * Writes 'V' (magic close character) to disable the watchdog before closing.
+ */
+export function stopWatchdog(): void {
+  if (watchdogTimer) {
+    clearInterval(watchdogTimer);
+    watchdogTimer = null;
+  }
+  if (watchdogFd !== null) {
+    try {
+      // Magic close character 'V' disables the watchdog
+      writeSync(watchdogFd, 'V');
+      closeSync(watchdogFd);
+    } catch { /* ignore close errors */ }
+    watchdogFd = null;
+  }
+}
+
+function petWatchdog(): void {
+  if (watchdogFd === null) return;
+  try {
+    writeSync(watchdogFd, '1');
+  } catch {
+    // If write fails, watchdog will trigger reboot — this is by design
+  }
+}

package/src/lib/screens.ts

@@ -0,0 +1,128 @@
+import { execSync } from 'child_process';
+import { getPlatform } from './platform.js';
+import type { Logger } from './logger.js';
+
+export interface DetectedScreen {
+  /** Windows display device ID, e.g. "\\.\DISPLAY1" */
+  hardwareId: string;
+  /** Friendly name / adapter description */
+  name: string;
+  /** Display index (0-based) */
+  index: number;
+  /** Screen bounds */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Whether this is the primary monitor */
+  primary: boolean;
+}
+
+/**
+ * Detect all connected displays on this machine.
+ * Windows: uses PowerShell + CIM to get monitor positions and IDs.
+ * Linux/macOS: uses xrandr / system_profiler (basic fallback).
+ */
+export function detectScreens(logger: Logger): DetectedScreen[] {
+  const platform = getPlatform();
+
+  if (platform === 'windows') {
+    return detectScreensWindows(logger);
+  }
+
+  if (platform === 'linux') {
+    return detectScreensLinux(logger);
+  }
+
+  logger.warn('[Screens] Screen detection not supported on this platform');
+  return [];
+}
+
+function detectScreensWindows(logger: Logger): DetectedScreen[] {
+  try {
+    // PowerShell script — use regular string to avoid JS template literal eating $variables
+    const psScript = [
+      'Add-Type -AssemblyName System.Windows.Forms;',
+      '$screens = [System.Windows.Forms.Screen]::AllScreens;',
+      '$result = @();',
+      '$i = 0;',
+      'foreach ($s in $screens) {',
+      '  $result += [PSCustomObject]@{',
+      '    hardwareId = $s.DeviceName;',
+      '    name = $s.DeviceName;',
+      '    index = $i;',
+      '    x = $s.Bounds.X;',
+      '    y = $s.Bounds.Y;',
+      '    width = $s.Bounds.Width;',
+      '    height = $s.Bounds.Height;',
+      '    primary = $s.Primary',
+      '  };',
+      '  $i++',
+      '};',
+      '$result | ConvertTo-Json -Compress',
+    ].join(' ');
+
+    const result = execSync('powershell -NoProfile -Command "' + psScript + '"', {
+      encoding: 'utf-8',
+      timeout: 10_000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).trim();
+
+    if (!result) {
+      logger.warn('[Screens] PowerShell returned empty result');
+      return [];
+    }
+
+    // PowerShell returns a single object (not array) when there's only 1 screen
+    const parsed = JSON.parse(result);
+    const screens: DetectedScreen[] = Array.isArray(parsed) ? parsed : [parsed];
+
+    logger.info(`[Screens] Detected ${screens.length} display(s)`);
+    for (const s of screens) {
+      logger.debug(`[Screens]   ${s.hardwareId} — ${s.width}x${s.height} @ (${s.x},${s.y})${s.primary ? ' [PRIMARY]' : ''}`);
+    }
+
+    return screens;
+  } catch (err) {
+    logger.error('[Screens] Failed to detect screens on Windows:', err instanceof Error ? err.message : String(err));
+    return [];
+  }
+}
+
+function detectScreensLinux(logger: Logger): DetectedScreen[] {
+  try {
+    const result = execSync('xrandr --query', {
+      encoding: 'utf-8',
+      timeout: 5_000,
+      stdio: ['pipe', 'pipe', 'ignore'],
+    });
+
+    const screens: DetectedScreen[] = [];
+    const lines = result.split('\n');
+    let index = 0;
+
+    for (const line of lines) {
+      // Match lines like: "HDMI-1 connected primary 1920x1080+0+0"
+      const match = line.match(/^(\S+)\s+connected\s+(primary\s+)?(\d+)x(\d+)\+(\d+)\+(\d+)/);
+      if (match) {
+        screens.push({
+          hardwareId: match[1],
+          name: match[1],
+          index,
+          x: parseInt(match[5], 10),
+          y: parseInt(match[6], 10),
+          width: parseInt(match[3], 10),
+          height: parseInt(match[4], 10),
+          primary: !!match[2],
+        });
+        index++;
+      }
+    }
+
+    logger.info(`[Screens] Detected ${screens.length} display(s) via xrandr`);
+    return screens;
+  } catch (err) {
+    logger.error('[Screens] Failed to detect screens on Linux:', err instanceof Error ? err.message : String(err));
+    return [];
+  }
+}