lightman-agent 1.0.0

package/src/commands/rpi.ts

@@ -0,0 +1,45 @@
+import type { CommandHandler } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+import { isRaspberryPi, getRpiInfo, getGpuTemp, getThrottled, isSdCardReadOnly, startWatchdog, stopWatchdog } from '../lib/rpi.js';
+
+export function registerRpiCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger
+): void {
+  // rpi:info — returns model, serial, revision, gpuTemp, throttled, sdCardReadOnly
+  register('rpi:info', async () => {
+    if (!isRaspberryPi()) {
+      throw new Error('Not a Raspberry Pi');
+    }
+    const info = getRpiInfo();
+    return {
+      ...info,
+      gpuTemp: getGpuTemp(),
+      throttled: getThrottled(),
+      sdCardReadOnly: isSdCardReadOnly(),
+    };
+  });
+
+  // rpi:watchdog-start — start hardware watchdog
+  register('rpi:watchdog-start', async () => {
+    if (!isRaspberryPi()) {
+      throw new Error('Not a Raspberry Pi');
+    }
+    const started = startWatchdog();
+    if (!started) {
+      throw new Error('Watchdog device not available. Ensure /dev/watchdog exists and agent has permissions.');
+    }
+    logger.info('Hardware watchdog started');
+    return { started: true };
+  });
+
+  // rpi:watchdog-stop — stop hardware watchdog gracefully
+  register('rpi:watchdog-stop', async () => {
+    if (!isRaspberryPi()) {
+      throw new Error('Not a Raspberry Pi');
+    }
+    stopWatchdog();
+    logger.info('Hardware watchdog stopped');
+    return { stopped: true };
+  });
+}

package/src/commands/screenshot.ts

@@ -0,0 +1,166 @@
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import type { CommandHandler } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+import { getPlatform } from '../lib/platform.js';
+
+const ALLOWED_CAPTURE_TOOLS = ['scrot', 'import', 'screencapture'] as const;
+
+// --- Zod Schema ---
+const ScreenshotArgsSchema = z.object({
+  serverUrl: z.string().url().optional(),
+  deviceId: z.string().uuid().optional(),
+  apiKey: z.string().min(1).optional(),
+  quality: z.number().int().min(1).max(100).optional(),
+});
+
+export function registerScreenshotCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger
+): void {
+  register('kiosk:screenshot', async (args) => {
+    const parsed = ScreenshotArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new Error(`Invalid screenshot args: ${parsed.error.issues.map((i) => i.message).join(', ')}`);
+    }
+
+    const { serverUrl, deviceId, apiKey, quality: parsedQuality } = parsed.data;
+    const quality = parsedQuality ?? 75;
+
+    const tmpFile = `/tmp/lightman-screenshot-${Date.now()}.jpg`;
+
+    try {
+      // --- Capture screenshot ---
+      const { tool, toolArgs } = resolveCapture(quality, tmpFile);
+      logger.info(`Capturing screenshot: ${tool} ${toolArgs.join(' ')}`);
+
+      execFileSync(tool, toolArgs, { timeout: 10_000, stdio: 'pipe' });
+
+      if (!fs.existsSync(tmpFile)) {
+        throw new Error('Screenshot file was not created');
+      }
+
+      const buffer = await fs.promises.readFile(tmpFile);
+      logger.info(`Screenshot captured: ${buffer.length} bytes`);
+
+      // --- Upload if server info provided ---
+      if (serverUrl && deviceId && apiKey) {
+        try {
+          const uploaded = await uploadScreenshot(
+            buffer,
+            tmpFile,
+            serverUrl,
+            deviceId,
+            apiKey,
+            logger
+          );
+          return { captured: true, size: buffer.length, uploaded };
+        } catch (uploadErr) {
+          const errMsg =
+            uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
+          logger.error('Screenshot upload failed:', errMsg);
+          return { captured: true, size: buffer.length, uploaded: false, error: errMsg };
+        }
+      }
+
+      return { captured: true, size: buffer.length, uploaded: false };
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      logger.error('Screenshot capture failed:', errMsg);
+      throw new Error(`Screenshot capture failed: ${errMsg}`);
+    } finally {
+      // Clean up temp file
+      try {
+        if (fs.existsSync(tmpFile)) {
+          await fs.promises.unlink(tmpFile);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  });
+}
+
+/**
+ * Determine the capture tool and arguments based on platform.
+ * No user-controlled command strings — only allowlisted tools with safe args.
+ */
+function resolveCapture(
+  quality: number,
+  tmpFile: string
+): { tool: string; toolArgs: string[] } {
+  const platform = getPlatform();
+
+  if (platform === 'linux') {
+    if (commandExists('scrot')) {
+      return { tool: 'scrot', toolArgs: ['-q', String(quality), tmpFile] };
+    }
+    if (commandExists('import')) {
+      return { tool: 'import', toolArgs: ['-window', 'root', '-quality', String(quality), tmpFile] };
+    }
+    throw new Error(
+      'No screenshot tool available. Install scrot or ImageMagick (import).'
+    );
+  }
+
+  if (platform === 'darwin') {
+    return { tool: 'screencapture', toolArgs: ['-x', '-t', 'jpg', tmpFile] };
+  }
+
+  throw new Error(`Screenshot capture not supported on platform: ${platform}`);
+}
+
+/**
+ * Check if a command exists on the system using execFileSync (no shell injection).
+ */
+function commandExists(cmd: string): boolean {
+  if (!ALLOWED_CAPTURE_TOOLS.includes(cmd as typeof ALLOWED_CAPTURE_TOOLS[number])) {
+    return false;
+  }
+  try {
+    execFileSync('which', [cmd], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Upload screenshot to server via multipart/form-data.
+ */
+async function uploadScreenshot(
+  buffer: Buffer,
+  filePath: string,
+  serverUrl: string,
+  deviceId: string,
+  apiKey: string,
+  logger: Logger
+): Promise<boolean> {
+  const endpoint = `/api/devices/${deviceId}/screenshot`;
+  const url = `${serverUrl}${endpoint}`;
+  const filename = path.basename(filePath);
+
+  logger.info(`Uploading screenshot to ${url}`);
+
+  const blob = new Blob([buffer], { type: 'image/jpeg' });
+  const formData = new FormData();
+  formData.append('screenshot', blob, filename);
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'x-api-key': apiKey,
+    },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new Error(`Upload failed: HTTP ${response.status} ${body}`);
+  }
+
+  logger.info('Screenshot uploaded successfully');
+  return true;
+}

package/src/commands/serial.ts

@@ -0,0 +1,17 @@
+import type { CommandHandler } from '../lib/types.js';
+import type { Logger } from '../lib/logger.js';
+
+// --- Register Serial Commands ---
+
+export function registerSerialCommands(
+  register: (command: string, handler: CommandHandler) => void,
+  logger: Logger
+): void {
+  // serial:close — placeholder
+  register('serial:close', async (args) => {
+    const port = args?.port as string;
+    if (!port) throw new Error('Port path is required');
+    logger.info(`serial:close requested for ${port}`);
+    return { status: 'acknowledged', port };
+  });
+}

package/src/commands/update.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import type { Logger } from '../lib/logger.js';
+import type { Updater } from '../services/updater.js';
+import type { WsClient } from '../services/websocket.js';
+import type { CommandHandler } from '../lib/types.js';
+
+type RegisterFn = (name: string, handler: CommandHandler) => void;
+
+// --- Zod Schemas ---
+const UpdateArgsSchema = z.object({
+  url: z.string().url().refine(
+    (val) => {
+      try {
+        const parsed = new URL(val);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+      } catch {
+        return false;
+      }
+    },
+    { message: 'Only http/https URLs are supported' }
+  ),
+  version: z.string().min(1),
+  checksum: z.string().regex(/^[a-f0-9]{64}$/i, 'Invalid checksum format (expected SHA256 hex)'),
+});
+
+export function registerUpdateCommands(
+  register: RegisterFn,
+  updater: Updater,
+  wsClient: WsClient,
+  logger: Logger
+): void {
+  /**
+   * agent:update — Download, verify, install an update, then restart.
+   * Args: { url: string, version: string, checksum: string }
+   */
+  register('agent:update', async (args) => {
+    const parsed = UpdateArgsSchema.safeParse(args ?? {});
+    if (!parsed.success) {
+      const issues = parsed.error.issues;
+      const urlIssue = issues.find((i) => i.path.includes('url'));
+      const checksumIssue = issues.find((i) => i.path.includes('checksum'));
+
+      if (urlIssue && urlIssue.code === 'invalid_string') {
+        throw new Error('Invalid URL');
+      }
+      if (urlIssue && urlIssue.message === 'Only http/https URLs are supported') {
+        throw new Error('Only http/https URLs are supported');
+      }
+      if (checksumIssue) {
+        throw new Error('Invalid checksum format (expected SHA256 hex)');
+      }
+      throw new Error('Missing required args: url, version, checksum');
+    }
+
+    const { url, version, checksum } = parsed.data;
+
+    // Send status update
+    const sendStatus = (phase: string, detail?: Record<string, unknown>) => {
+      wsClient.send({
+        type: 'agent:update_status',
+        payload: { phase, version, ...detail },
+        timestamp: Date.now(),
+      });
+    };
+
+    try {
+      sendStatus('downloading');
+      const filePath = await updater.download(url);
+
+      sendStatus('verifying');
+      const valid = await updater.verify(filePath, checksum);
+      if (!valid) {
+        sendStatus('error', { error: 'Checksum verification failed' });
+        throw new Error('Checksum verification failed');
+      }
+
+      sendStatus('installing');
+      await updater.install(filePath, version);
+
+      // Clean old downloads
+      updater.cleanDownloads();
+
+      sendStatus('restarting');
+      logger.info(`Update to v${version} complete. Restarting...`);
+
+      // Delay restart to allow result to be sent
+      setTimeout(() => process.exit(0), 2000);
+
+      return { success: true, version, restarting: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      sendStatus('error', { error: message });
+      logger.error(`Update failed: ${message}`);
+      throw new Error(`Update failed: ${message}`);
+    }
+  });
+
+  /**
+   * agent:rollback — Rollback to the previous backup version.
+   */
+  register('agent:rollback', async () => {
+    try {
+      await updater.rollback();
+      logger.info('Rollback complete. Restarting...');
+
+      // Delay restart to allow result to be sent
+      setTimeout(() => process.exit(0), 2000);
+
+      return { success: true, restarting: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`Rollback failed: ${message}`);
+      throw new Error(`Rollback failed: ${message}`);
+    }
+  });
+
+  /**
+   * agent:update-status — Get current update status.
+   */
+  register('agent:update-status', async () => {
+    const status = updater.getStatus();
+    return { ...status } as Record<string, unknown>;
+  });
+}