lightman-agent 1.0.0

package/src/commands/display.ts

@@ -0,0 +1,177 @@
+import { execFile, spawn } from 'child_process';
+import { z } from 'zod';
+import type { CommandHandler } from '../lib/types.js';
+import { getPlatform } from '../lib/platform.js';
+import type { Logger } from '../lib/logger.js';
+
+// --- Zod Schemas ---
+const BrightnessArgsSchema = z.object({
+  level: z.number().int().min(0).max(100),
+});
+
+const PowerArgsSchema = z.object({
+  state: z.enum(['on', 'off', 'standby']),
+});
+
+const RotateArgsSchema = z.object({
+  rotation: z.enum(['normal', 'left', 'right', 'inverted']),
+});
+
+const VolumeArgsSchema = z.object({
+  level: z.number().int().min(0).max(100),
+});
+
+function execFilePromise(cmd: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(stderr || err.message));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+/**
+ * Pipe data to a command via stdin using spawn (no shell).
+ */
+function spawnWithStdin(cmd: string, args: string[], stdinData: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data: Buffer) => { stdout += data.toString(); });
+    child.stderr.on('data', (data: Buffer) => { stderr += data.toString(); });
+
+    child.on('error', (err) => reject(new Error(err.message)));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(stderr || `Process exited with code ${code}`));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+
+    child.stdin.write(stdinData);
+    child.stdin.end();
+  });
+}
+
+/**
+ * Detect the primary connected display output name from xrandr.
+ */
+async function getConnectedDisplay(): Promise<string> {
+  const output = await execFilePromise('xrandr', []);
+  const match = output.match(/^(\S+)\s+connected/m);
+  if (!match) {
+    throw new Error('No connected display found');
+  }
+  return match[1];
+}
+
+export function registerDisplayCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger
+): void {
+  // display:brightness — set screen brightness (Linux only)
+  register('display:brightness', async (args) => {
+    if (getPlatform() !== 'linux') {
+      throw new Error('Not supported on this platform');
+    }
+
+    const parsed = BrightnessArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error('Invalid brightness level, must be 0-100');
+    }
+
+    const { level } = parsed.data;
+    const brightness = (level / 100).toFixed(2);
+
+    logger.info(`Setting brightness to ${level}%`);
+
+    const display = await getConnectedDisplay();
+    await execFilePromise('xrandr', ['--output', display, '--brightness', brightness]);
+    return { level };
+  });
+
+  // display:power — control display power via CEC (Linux only)
+  register('display:power', async (args) => {
+    if (getPlatform() !== 'linux') {
+      throw new Error('Not supported on this platform');
+    }
+
+    const parsed = PowerArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error('Invalid state, must be on | off | standby');
+    }
+
+    const { state } = parsed.data;
+
+    const cecCommands: Readonly<Record<string, string>> = {
+      on: 'on 0',
+      off: 'standby 0',
+      standby: 'standby 0',
+    };
+
+    const cecCmd = cecCommands[state];
+
+    logger.info(`Setting display power to ${state}`);
+
+    // Pipe CEC command via spawn stdin (no shell)
+    await spawnWithStdin('cec-client', ['-s', '-d', '1'], cecCmd + '\n');
+    return { state };
+  });
+
+  // display:rotate — rotate display output (Linux only)
+  register('display:rotate', async (args) => {
+    if (getPlatform() !== 'linux') {
+      throw new Error('Not supported on this platform');
+    }
+
+    const parsed = RotateArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error('Invalid rotation, must be normal | left | right | inverted');
+    }
+
+    const { rotation } = parsed.data;
+
+    logger.info(`Setting display rotation to ${rotation}`);
+
+    const display = await getConnectedDisplay();
+    await execFilePromise('xrandr', ['--output', display, '--rotate', rotation]);
+    return { rotation };
+  });
+
+  // display:volume — set audio volume (Linux only)
+  register('display:volume', async (args) => {
+    if (getPlatform() !== 'linux') {
+      throw new Error('Not supported on this platform');
+    }
+
+    const parsed = VolumeArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error('Invalid volume level, must be 0-100');
+    }
+
+    const { level } = parsed.data;
+
+    logger.info(`Setting volume to ${level}%`);
+
+    await execFilePromise('amixer', ['set', 'Master', `${level}%`]);
+    return { level };
+  });
+
+  // display:info — query display information (Linux with fallback)
+  register('display:info', async () => {
+    if (getPlatform() !== 'linux') {
+      throw new Error('Not supported on this platform');
+    }
+
+    logger.info('Querying display info');
+
+    const stdout = await execFilePromise('xrandr', ['--query']);
+    return { raw: stdout };
+  });
+}

package/src/commands/kiosk.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import type { CommandHandler, KioskStatus } from '../lib/types.js';
+import type { KioskManager } from '../services/kiosk.js';
+import type { MultiScreenKioskManager } from '../services/multiScreenKiosk.js';
+import type { Logger } from '../lib/logger.js';
+
+// --- Zod Schemas ---
+const HttpUrlSchema = z.string().url().refine(
+  (val) => {
+    try {
+      const parsed = new URL(val);
+      return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    } catch {
+      return false;
+    }
+  },
+  { message: 'Must be a valid http/https URL' }
+);
+
+const LaunchArgsSchema = z.object({
+  url: HttpUrlSchema.optional(),
+});
+
+const NavigateArgsSchema = z.object({
+  url: HttpUrlSchema,
+});
+
+export function registerKioskCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  kioskManager: KioskManager,
+  logger: Logger
+): void {
+  register('kiosk:launch', async (args) => {
+    const parsed = LaunchArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error('kiosk:launch requires a valid http/https URL');
+    }
+    const { url } = parsed.data;
+    logger.info(`kiosk:launch${url ? ` → ${url}` : ' (default URL)'}`);
+    const status: KioskStatus = await kioskManager.launch(url);
+    return status as unknown as Record<string, unknown>;
+  });
+
+  register('kiosk:kill', async () => {
+    logger.info('kiosk:kill');
+    await kioskManager.kill();
+    return { killed: true };
+  });
+
+  register('kiosk:navigate', async (args) => {
+    const parsed = NavigateArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      const hasUrl = typeof args?.url === 'string' && args.url.length > 0;
+      if (!hasUrl) {
+        throw new Error('kiosk:navigate requires args.url');
+      }
+      throw new Error('kiosk:navigate requires a valid http/https URL');
+    }
+    const { url } = parsed.data;
+    logger.info(`kiosk:navigate → ${url}`);
+    await kioskManager.navigate(url);
+    return { navigated: true, url };
+  });
+
+  register('kiosk:restart', async () => {
+    logger.info('kiosk:restart');
+    const status: KioskStatus = await kioskManager.restart();
+    return status as unknown as Record<string, unknown>;
+  });
+
+  register('kiosk:status', async () => {
+    const status: KioskStatus = kioskManager.getStatus();
+    return status as unknown as Record<string, unknown>;
+  });
+}
+
+/**
+ * Register multi-screen kiosk commands.
+ * These allow the server to manage individual screens on multi-display devices.
+ */
+export function registerMultiScreenKioskCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  multiKiosk: MultiScreenKioskManager,
+  getIdentity: () => { deviceId: string; apiKey: string },
+  logger: Logger
+): void {
+  register('kiosk:multi:status', async () => {
+    const status = multiKiosk.getStatus();
+    return status as unknown as Record<string, unknown>;
+  });
+
+  register('kiosk:multi:navigate', async (args) => {
+    const hardwareId = args?.hardwareId as string;
+    const url = args?.url as string;
+    if (!hardwareId) throw new Error('kiosk:multi:navigate requires args.hardwareId');
+    if (!url) throw new Error('kiosk:multi:navigate requires args.url');
+    logger.info(`kiosk:multi:navigate ${hardwareId} → ${url}`);
+    await multiKiosk.navigateScreen(hardwareId, url, getIdentity());
+    return { navigated: true, hardwareId, url };
+  });
+
+  register('kiosk:multi:restart', async () => {
+    logger.info('kiosk:multi:restart');
+    const status = await multiKiosk.restartAll(getIdentity());
+    return status as unknown as Record<string, unknown>;
+  });
+
+  register('kiosk:multi:kill', async () => {
+    logger.info('kiosk:multi:kill');
+    await multiKiosk.killAll();
+    return { killed: true };
+  });
+}

package/src/commands/maintenance.ts

@@ -0,0 +1,106 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import type { CommandHandler } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+import type { Watchdog } from '../services/watchdog.js';
+
+export function registerMaintenanceCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  watchdog: Watchdog,
+  logger: Logger
+): void {
+  // maintenance:cleanup — Run disk cleanup immediately
+  register('maintenance:cleanup', async () => {
+    logger.info('Manual disk cleanup requested');
+    const result = await watchdog.runDiskCleanup();
+    return { ...result };
+  });
+
+  // maintenance:status — Get watchdog recovery stats
+  register('maintenance:status', async () => {
+    const stats = watchdog.getStats();
+    const cooldowns = watchdog.getCooldowns();
+    return { stats, cooldowns };
+  });
+
+  // maintenance:restore-desktop — Switch from shell replacement back to normal desktop
+  // After this command, machine needs a reboot to take effect.
+  register('maintenance:restore-desktop', async () => {
+    if (process.platform !== 'win32') {
+      return { restored: false, message: 'Only available on Windows' };
+    }
+
+    logger.warn('RESTORE DESKTOP: Switching Windows shell back to explorer.exe');
+
+    try {
+      // Restore HKLM shell to explorer.exe
+      execSync(
+        'reg add "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon" /v Shell /d explorer.exe /f',
+        { stdio: 'ignore', timeout: 10_000 }
+      );
+      // Remove HKCU shell override
+      execSync(
+        'reg delete "HKCU\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon" /v Shell /f',
+        { stdio: 'ignore', timeout: 10_000 }
+      );
+    } catch {
+      // HKCU key may not exist, that's fine
+    }
+
+    // Also set shellMode: false in the config so agent resumes normal kiosk management
+    try {
+      const configPath = resolve(process.cwd(), 'agent.config.json');
+      const raw = readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(raw);
+      if (config.kiosk) {
+        config.kiosk.shellMode = false;
+      }
+      writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+      logger.info('Config updated: shellMode set to false');
+    } catch (err) {
+      logger.error('Failed to update config:', err instanceof Error ? err.message : String(err));
+    }
+
+    logger.warn('Desktop restored. Machine needs a REBOOT to take effect.');
+    return { restored: true, message: 'Desktop restored. Reboot required.' };
+  });
+
+  // maintenance:enable-shell — Switch from normal desktop to shell replacement mode
+  // After this command, machine needs a reboot to take effect.
+  register('maintenance:enable-shell', async () => {
+    if (process.platform !== 'win32') {
+      return { enabled: false, message: 'Only available on Windows' };
+    }
+
+    const shellBat = resolve(process.cwd(), 'lightman-shell.bat');
+    logger.warn(`ENABLE SHELL: Switching Windows shell to ${shellBat}`);
+
+    try {
+      // Set shell to lightman-shell.bat
+      execSync(
+        `reg add "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon" /v Shell /d "\\"${shellBat}\\"" /f`,
+        { stdio: 'ignore', timeout: 10_000 }
+      );
+    } catch (err) {
+      return { enabled: false, message: `Registry update failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+
+    // Update config to shellMode: true
+    try {
+      const configPath = resolve(process.cwd(), 'agent.config.json');
+      const raw = readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(raw);
+      if (config.kiosk) {
+        config.kiosk.shellMode = true;
+      }
+      writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+      logger.info('Config updated: shellMode set to true');
+    } catch (err) {
+      logger.error('Failed to update config:', err instanceof Error ? err.message : String(err));
+    }
+
+    logger.warn('Shell mode enabled. Machine needs a REBOOT to take effect.');
+    return { enabled: true, message: 'Shell mode enabled. Reboot required.' };
+  });
+}

package/src/commands/network.ts

@@ -0,0 +1,129 @@
+import net from 'net';
+import dns from 'dns';
+import { URL } from 'url';
+import si from 'systeminformation';
+import type { CommandHandler } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+
+export function registerNetworkCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger,
+  serverUrl: string
+): void {
+  // network:ping — TCP connect to CMS server, measure round-trip
+  register('network:ping', async () => {
+    const url = new URL(serverUrl);
+    const host = url.hostname;
+    const port = parseInt(url.port, 10) || 3001;
+
+    const start = Date.now();
+    const reachable = await tcpPing(host, port, 5000);
+    const latencyMs = Date.now() - start;
+
+    logger.info(`Network ping: ${host}:${port} → ${reachable ? 'OK' : 'FAIL'} (${latencyMs}ms)`);
+    return { latency_ms: latencyMs, reachable, host, port };
+  });
+
+  // network:bandwidth — Download 1MB test file, measure speed
+  register('network:bandwidth', async () => {
+    const url = `${serverUrl}/api/agent/bandwidth-test`;
+    logger.info(`Bandwidth test: downloading from ${url}`);
+
+    const start = Date.now();
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      const buffer = await response.arrayBuffer();
+      const durationMs = Date.now() - start;
+      const sizeMb = buffer.byteLength / (1024 * 1024);
+      const speedMbps = (sizeMb * 8) / (durationMs / 1000);
+
+      logger.info(`Bandwidth: ${speedMbps.toFixed(2)} Mbps (${buffer.byteLength} bytes in ${durationMs}ms)`);
+      return {
+        speed_mbps: Math.round(speedMbps * 100) / 100,
+        duration_ms: durationMs,
+        bytes: buffer.byteLength,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error('Bandwidth test failed:', message);
+      throw new Error(`Bandwidth test failed: ${message}`);
+    }
+  });
+
+  // network:dns — Resolve CMS hostname
+  register('network:dns', async () => {
+    const url = new URL(serverUrl);
+    const hostname = url.hostname;
+
+    logger.info(`DNS resolve: ${hostname}`);
+    const start = Date.now();
+
+    try {
+      const addresses = await new Promise<string[]>((resolve, reject) => {
+        dns.resolve(hostname, (err, addrs) => {
+          if (err) reject(err);
+          else resolve(addrs);
+        });
+      });
+      const timeMs = Date.now() - start;
+
+      logger.info(`DNS resolved: ${hostname} → ${addresses.join(', ')} (${timeMs}ms)`);
+      return { resolved: true, addresses, time_ms: timeMs, hostname };
+    } catch (err) {
+      const timeMs = Date.now() - start;
+      // If it's an IP address, DNS resolve will fail — that's OK
+      if (net.isIP(hostname)) {
+        return { resolved: true, addresses: [hostname], time_ms: timeMs, hostname, note: 'IP address (no DNS needed)' };
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error('DNS resolve failed:', message);
+      return { resolved: false, addresses: [], time_ms: timeMs, hostname, error: message };
+    }
+  });
+
+  // network:interfaces — List network interfaces
+  register('network:interfaces', async () => {
+    const ifaces = await si.networkInterfaces();
+    const ifaceList = Array.isArray(ifaces) ? ifaces : [ifaces];
+
+    const interfaces = ifaceList
+      .filter((iface) => !iface.internal && iface.ip4)
+      .map((iface) => ({
+        name: iface.iface,
+        ip4: iface.ip4,
+        mac: iface.mac,
+        speed: iface.speed,
+        type: iface.type,
+      }));
+
+    logger.info(`Network interfaces: ${interfaces.length} found`);
+    return { interfaces };
+  });
+}
+
+/**
+ * TCP ping: attempt a TCP connection and measure latency.
+ * Returns true if connection succeeds within timeout.
+ */
+function tcpPing(host: string, port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let resolved = false;
+
+    const done = (result: boolean) => {
+      if (resolved) return;
+      resolved = true;
+      socket.destroy();
+      resolve(result);
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => done(true));
+    socket.on('timeout', () => done(false));
+    socket.on('error', () => done(false));
+    socket.connect(port, host);
+  });
+}

package/src/commands/power.ts

@@ -0,0 +1,163 @@
+import { execFile } from 'child_process';
+import { z } from 'zod';
+import type { CommandHandler } from '../lib/types.js';
+import { getPlatform } from '../lib/platform.js';
+import type { Logger } from '../lib/logger.js';
+
+// --- Zod Schemas ---
+const ShutdownDelayedArgsSchema = z.object({
+  delayMs: z.number().finite().optional(),
+});
+
+let pendingShutdown: ReturnType<typeof setTimeout> | null = null;
+
+interface ExecCommand {
+  readonly bin: string;
+  readonly args: readonly string[];
+}
+
+function execCommand(cmd: ExecCommand, logger: Logger): void {
+  execFile(cmd.bin, [...cmd.args], (err, stdout, stderr) => {
+    if (err) {
+      logger.error(`Exec failed: ${cmd.bin}`, err.message);
+    }
+    if (stderr) {
+      logger.warn(`Exec stderr: ${cmd.bin}`, stderr);
+    }
+    if (stdout) {
+      logger.debug(`Exec stdout: ${cmd.bin}`, stdout);
+    }
+  });
+}
+
+function getShutdownCommand(): ExecCommand {
+  const platform = getPlatform();
+  switch (platform) {
+    case 'windows':
+      return { bin: 'shutdown', args: ['/s', '/t', '0'] };
+    case 'darwin':
+    case 'linux':
+    default:
+      return { bin: 'shutdown', args: ['-h', 'now'] };
+  }
+}
+
+function getRebootCommand(): ExecCommand {
+  const platform = getPlatform();
+  switch (platform) {
+    case 'windows':
+      return { bin: 'shutdown', args: ['/r', '/t', '0'] };
+    case 'darwin':
+    case 'linux':
+    default:
+      return { bin: 'shutdown', args: ['-r', 'now'] };
+  }
+}
+
+function getSuspendCommand(): ExecCommand {
+  const platform = getPlatform();
+  switch (platform) {
+    case 'linux':
+      return { bin: 'systemctl', args: ['suspend'] };
+    case 'windows':
+      return { bin: 'rundll32.exe', args: ['powrprof.dll,SetSuspendState', '0,1,0'] };
+    case 'darwin':
+      return { bin: 'pmset', args: ['sleepnow'] };
+    default:
+      return { bin: 'systemctl', args: ['suspend'] };
+  }
+}
+
+export function registerPowerCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger
+): void {
+  // system:shutdown — graceful shutdown with 5s delay
+  register('system:shutdown', async () => {
+    const cmd = getShutdownCommand();
+    logger.info(`Scheduling shutdown in 5000ms: ${cmd}`);
+
+    setTimeout(() => {
+      try {
+        execCommand(cmd, logger);
+      } catch (err) {
+        logger.error('Shutdown exec error', err instanceof Error ? err.message : String(err));
+      }
+    }, 5000);
+
+    return { delayed: true, delayMs: 5000 };
+  });
+
+  // system:reboot — graceful reboot with 5s delay
+  register('system:reboot', async () => {
+    const cmd = getRebootCommand();
+    logger.info(`Scheduling reboot in 5000ms: ${cmd}`);
+
+    setTimeout(() => {
+      try {
+        execCommand(cmd, logger);
+      } catch (err) {
+        logger.error('Reboot exec error', err instanceof Error ? err.message : String(err));
+      }
+    }, 5000);
+
+    return { delayed: true, delayMs: 5000 };
+  });
+
+  // system:suspend — immediate suspend
+  register('system:suspend', async () => {
+    const cmd = getSuspendCommand();
+    logger.info(`Executing suspend: ${cmd}`);
+
+    try {
+      execCommand(cmd, logger);
+    } catch (err) {
+      logger.error('Suspend exec error', err instanceof Error ? err.message : String(err));
+    }
+
+    return { suspended: true };
+  });
+
+  // system:shutdown-delayed — shutdown after configurable delay (5s to 24h)
+  register('system:shutdown-delayed', async (args) => {
+    const parsed = ShutdownDelayedArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error(`Invalid args: ${parsed.error.issues.map((i) => i.message).join(', ')}`);
+    }
+    const rawDelay = parsed.data.delayMs ?? 60000;
+    const delayMs = Math.max(5000, Math.min(rawDelay, 86_400_000));
+    const cmd = getShutdownCommand();
+
+    logger.info(`Scheduling delayed shutdown in ${delayMs}ms: ${cmd}`);
+
+    // Clear any existing pending shutdown
+    if (pendingShutdown !== null) {
+      clearTimeout(pendingShutdown);
+      logger.info('Cleared previous pending shutdown');
+    }
+
+    pendingShutdown = setTimeout(() => {
+      try {
+        execCommand(cmd, logger);
+      } catch (err) {
+        logger.error('Delayed shutdown exec error', err instanceof Error ? err.message : String(err));
+      }
+      pendingShutdown = null;
+    }, delayMs);
+
+    return { delayed: true, delayMs };
+  });
+
+  // system:cancel-shutdown — cancel a pending delayed shutdown
+  register('system:cancel-shutdown', async () => {
+    if (pendingShutdown !== null) {
+      clearTimeout(pendingShutdown);
+      pendingShutdown = null;
+      logger.info('Pending shutdown cancelled');
+      return { cancelled: true };
+    }
+
+    logger.info('No pending shutdown to cancel');
+    return { cancelled: false, reason: 'no pending shutdown' };
+  });
+}