feat: implement comprehensive printer discovery and connection system

This implementation adds full WebUI-based printer discovery, connection,
and management capabilities, bridging the gap that previously prevented
proper printer connections via CLI flags.

Backend Changes:
- Enhanced ConnectionEstablishmentService with timeout handling (10s),
  retry logic (3 attempts with exponential backoff), and improved error
  logging to fix CLI connection hangs
- Added discovery API routes (/api/discovery/scan, /api/discovery/scan-ip,
  /api/discovery/status, /api/discovery/cancel) for network scanning
- Added printer management routes (/api/printers/connect,
  /api/printers/disconnect, /api/printers/saved, /api/printers/reconnect)
- Integrated services with proper error handling and validation

Frontend Changes:
- Created printer-discovery feature with tabbed modal interface:
  * Network Scan tab: Auto-discover printers on local network
  * Manual Entry tab: Direct IP connection with printer type selection
  * Saved Printers tab: Reconnect to previously connected printers
- Added "Add Printer" button to header for easy access
- Implemented real-time discovery status updates and spinner
- Added printer card UI with connection status badges
- Full support for both 5M/Pro (new API) and legacy printers

Key Features:
- Network-wide printer discovery with IP matching
- Saved printer management (reconnect, delete)
- Smart printer type detection (5M family vs legacy)
- Check code validation for 5M/Pro printers
- IP address change detection for saved printers
- Comprehensive error handling and user feedback

This resolves the issue where CLI connections would hang during handshake
and enables full discovery/connection workflows from the WebUI, allowing
users to discover printers, match IPs, fetch serials for authentication,
and establish connections without CLI flags.

Author: claude

src/services/ConnectionEstablishmentService.ts

@@ -60,84 +60,169 @@ export class ConnectionEstablishmentService extends EventEmitter {
   /**
    * Create temporary connection to determine printer type
    * Uses legacy API for universal compatibility
+   * Includes timeout handling and retry logic
    */
-  public async createTemporaryConnection(printer: DiscoveredPrinter): Promise<TemporaryConnectionResult> {
+  public async createTemporaryConnection(
+    printer: DiscoveredPrinter,
+    timeout = 10000,
+    retries = 3
+  ): Promise<TemporaryConnectionResult> {
     this.emit('temporary-connection-started', printer);
 
-    try {
-      // Always use legacy API for type detection
-      const tempClient = new FlashForgeClient(printer.ipAddress);
-      const connected = await tempClient.initControl();
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      let tempClient: FlashForgeClient | null = null;
 
-      if (!connected) {
-        this.emit('temporary-connection-failed', 'Failed to establish temporary connection');
-        return {
-          success: false,
-          error: 'Failed to establish temporary connection'
-        };
-      }
+      try {
+        console.log(`[Connection] Attempt ${attempt}/${retries} for ${printer.ipAddress}`);
 
-      // Get printer info to determine type
-      const printerInfo = await tempClient.getPrinterInfo();
-      if (!printerInfo || !printerInfo.TypeName) {
-        void tempClient.dispose();
-        this.emit('temporary-connection-failed', 'Failed to get printer type information');
-        return {
-          success: false,
-          error: 'Failed to get printer type information'
-        };
-      }
+        // Always use legacy API for type detection
+        tempClient = new FlashForgeClient(printer.ipAddress);
 
-      const typeName = printerInfo.TypeName;
-      const familyInfo = detectPrinterFamily(typeName);
-      
-      console.log('Temporary connection - extracted printer info:', {
-        TypeName: printerInfo.TypeName,
-        Name: printerInfo.Name,
-        SerialNumber: printerInfo.SerialNumber,
-        is5MFamily: familyInfo.is5MFamily
-      });
-      
-      this.emit('printer-type-detected', { typeName, familyInfo });
-      
-      // For legacy printers, we can reuse this connection
-      if (!familyInfo.is5MFamily) {
-        return {
-          success: true,
-          typeName,
-          printerInfo: {
-            ...(printerInfo as unknown as Record<string, unknown>),
-            _reuseableClient: tempClient // Store for reuse
+        // Wrap initControl in timeout
+        console.log(`[Connection] Initializing control connection (timeout: ${timeout}ms)...`);
+        const connected = await Promise.race([
+          tempClient.initControl(),
+          new Promise<boolean>((_, reject) =>
+            setTimeout(() => reject(new Error('Connection timeout')), timeout)
+          )
+        ]);
+
+        if (!connected) {
+          console.error(`[Connection] initControl returned false for ${printer.ipAddress}`);
+          if (tempClient) {
+            try {
+              void tempClient.dispose();
+            } catch (disposeError) {
+              console.error('[Connection] Error disposing temp client after initControl failure:', disposeError);
+            }
           }
-        };
-      } else {
-        // 5M family - dispose temp client, will create new one
-        // But first ensure we have critical information for dual API connection
-        if (!printerInfo.SerialNumber || printerInfo.SerialNumber.trim() === '') {
-          console.warn('Warning: No serial number found in printer info for 5M family printer');
-          console.warn('This may cause dual API connection to fail');
+
+          if (attempt < retries) {
+            await this.delay(1000 * attempt); // Exponential backoff
+            continue;
+          }
+
+          this.emit('temporary-connection-failed', 'Failed to initialize control');
+          return {
+            success: false,
+            error: 'Failed to initialize control'
+          };
+        }
+
+        console.log(`[Connection] Control initialized, fetching printer info (timeout: ${timeout}ms)...`);
+
+        // Get printer info with timeout
+        const printerInfo = await Promise.race([
+          tempClient.getPrinterInfo(),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error('Printer info timeout')), timeout)
+          )
+        ]);
+
+        if (!printerInfo || !printerInfo.TypeName) {
+          console.error(`[Connection] Invalid printer info received`);
+          if (tempClient) {
+            void tempClient.dispose();
+          }
+
+          if (attempt < retries) {
+            await this.delay(1000 * attempt);
+            continue;
+          }
+
+          this.emit('temporary-connection-failed', 'Failed to get printer type information');
+          return {
+            success: false,
+            error: 'Failed to get printer type information'
+          };
         }
-        
-        void tempClient.dispose();
-        
-        // Add a small delay after disposing temp client to ensure clean state
-        await new Promise(resolve => setTimeout(resolve, 200));
-        
+
+        const typeName = printerInfo.TypeName;
+        const familyInfo = detectPrinterFamily(typeName);
+
+        console.log('[Connection] Temporary connection successful - extracted printer info:', {
+          TypeName: printerInfo.TypeName,
+          Name: printerInfo.Name,
+          SerialNumber: printerInfo.SerialNumber,
+          is5MFamily: familyInfo.is5MFamily
+        });
+
+        this.emit('printer-type-detected', { typeName, familyInfo });
+
+        // For legacy printers, we can reuse this connection
+        if (!familyInfo.is5MFamily) {
+          console.log('[Connection] Legacy printer detected, reusing connection');
+          return {
+            success: true,
+            typeName,
+            printerInfo: {
+              ...(printerInfo as unknown as Record<string, unknown>),
+              _reuseableClient: tempClient // Store for reuse
+            }
+          };
+        } else {
+          // 5M family - dispose temp client, will create new one
+          // But first ensure we have critical information for dual API connection
+          if (!printerInfo.SerialNumber || printerInfo.SerialNumber.trim() === '') {
+            console.warn('[Connection] Warning: No serial number found in printer info for 5M family printer');
+            console.warn('[Connection] This may cause dual API connection to fail');
+          }
+
+          console.log('[Connection] 5M family printer detected, disposing temporary connection');
+          void tempClient.dispose();
+
+          // Add a small delay after disposing temp client to ensure clean state
+          await new Promise(resolve => setTimeout(resolve, 200));
+
+          return {
+            success: true,
+            typeName,
+            printerInfo: printerInfo as unknown as ExtendedPrinterInfo
+          };
+        }
+
+      } catch (error) {
+        console.error(`[Connection] Attempt ${attempt} failed:`, error);
+
+        // Clean up temp client on error
+        if (tempClient) {
+          try {
+            void tempClient.dispose();
+          } catch (disposeError) {
+            console.error('[Connection] Error disposing temp client after error:', disposeError);
+          }
+        }
+
+        if (attempt < retries) {
+          const backoffDelay = 1000 * attempt;
+          console.log(`[Connection] Retrying in ${backoffDelay}ms...`);
+          await this.delay(backoffDelay);
+          continue;
+        }
+
+        // All retries exhausted
+        const errorMessage = getConnectionErrorMessage(error);
+        console.error(`[Connection] All ${retries} attempts failed:`, errorMessage);
+        this.emit('temporary-connection-failed', errorMessage);
         return {
-          success: true,
-          typeName,
-          printerInfo: printerInfo as unknown as ExtendedPrinterInfo
+          success: false,
+          error: errorMessage
         };
       }
-
-    } catch (error) {
-      const errorMessage = getConnectionErrorMessage(error);
-      this.emit('temporary-connection-failed', errorMessage);
-      return {
-        success: false,
-        error: errorMessage
-      };
     }
+
+    // Should never reach here, but TypeScript requires it
+    return {
+      success: false,
+      error: 'All connection attempts failed'
+    };
+  }
+
+  /**
+   * Delay helper for exponential backoff
+   */
+  private async delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
   }
 
   /**

src/webui/server/api-routes.ts

@@ -22,6 +22,8 @@ import { registerCameraRoutes } from './routes/camera-routes';
 import { registerContextRoutes } from './routes/context-routes';
 import { registerThemeRoutes } from './routes/theme-routes';
 import { registerSpoolmanRoutes } from './routes/spoolman-routes';
+import { registerDiscoveryRoutes } from './routes/discovery-routes';
+import { registerPrinterManagementRoutes } from './routes/printer-management-routes';
 
 export function buildRouteDependencies(): RouteDependencies {
   return {
@@ -45,6 +47,8 @@ export function createAPIRoutes(deps: RouteDependencies = buildRouteDependencies
   registerContextRoutes(router, deps);
   registerThemeRoutes(router, deps);
   registerSpoolmanRoutes(router, deps);
+  registerDiscoveryRoutes(router, deps);
+  registerPrinterManagementRoutes(router, deps);
 
   return router;
 }

src/webui/server/routes/discovery-routes.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Discovery API Routes
+ * Handles network scanning and printer discovery
+ */
+
+import type { Router, Response } from 'express';
+import type { AuthenticatedRequest } from '../auth-middleware';
+import { StandardAPIResponse } from '../../types/web-api.types';
+import { toAppError } from '../../../utils/error.utils';
+import type { RouteDependencies } from './route-helpers';
+import { sendErrorResponse } from './route-helpers';
+import { getPrinterDiscoveryService } from '../../../services/PrinterDiscoveryService';
+import { getSavedPrinterService } from '../../../services/SavedPrinterService';
+
+export function registerDiscoveryRoutes(router: Router, _deps: RouteDependencies): void {
+  const discoveryService = getPrinterDiscoveryService();
+  const savedPrinterService = getSavedPrinterService();
+
+  /**
+   * POST /api/discovery/scan
+   * Start network-wide printer discovery
+   */
+  router.post('/discovery/scan', async (req: AuthenticatedRequest, res: Response) => {
+    try {
+      const body = req.body as {
+        timeout?: number;
+        interval?: number;
+        retries?: number;
+      };
+
+      const timeout = typeof body.timeout === 'number' ? body.timeout : 10000;
+      const interval = typeof body.interval === 'number' ? body.interval : 2000;
+      const retries = typeof body.retries === 'number' ? body.retries : 3;
+
+      // Validate parameters
+      if (timeout < 1000 || timeout > 60000) {
+        return sendErrorResponse(res, 400, 'Timeout must be between 1000 and 60000ms');
+      }
+      if (interval < 500 || interval > 5000) {
+        return sendErrorResponse(res, 400, 'Interval must be between 500 and 5000ms');
+      }
+      if (retries < 1 || retries > 5) {
+        return sendErrorResponse(res, 400, 'Retries must be between 1 and 5');
+      }
+
+      // Check if discovery is already running
+      if (discoveryService.isDiscoveryInProgress()) {
+        return sendErrorResponse(res, 409, 'Discovery already in progress');
+      }
+
+      // Start discovery
+      const discoveredPrinters = await discoveryService.scanNetwork(timeout, interval, retries);
+
+      // Match with saved printers
+      const savedPrinters = savedPrinterService.getSavedPrinters();
+      const savedMatches = discoveredPrinters.map(discovered => {
+        const saved = savedPrinters.find(s => s.SerialNumber === discovered.serialNumber);
+        return {
+          discovered,
+          saved: saved || null,
+          isKnown: !!saved,
+          ipAddressChanged: saved ? saved.IPAddress !== discovered.ipAddress : false
+        };
+      });
+
+      return res.json({
+        success: true,
+        printers: discoveredPrinters,
+        savedMatches,
+        count: discoveredPrinters.length
+      });
+
+    } catch (error) {
+      console.error('[API] Discovery scan failed:', error);
+      const appError = toAppError(error);
+      return sendErrorResponse(res, 500, appError.message);
+    }
+  });
+
+  /**
+   * POST /api/discovery/scan-ip
+   * Scan a specific IP address for a printer
+   */
+  router.post('/discovery/scan-ip', async (req: AuthenticatedRequest, res: Response) => {
+    try {
+      const body = req.body as { ipAddress?: string };
+      const ipAddress = body.ipAddress;
+
+      if (!ipAddress || typeof ipAddress !== 'string') {
+        return sendErrorResponse(res, 400, 'IP address is required');
+      }
+
+      // Basic IP validation
+      const ipRegex = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
+      if (!ipRegex.test(ipAddress)) {
+        return sendErrorResponse(res, 400, 'Invalid IP address format');
+      }
+
+      const printer = await discoveryService.scanSingleIP(ipAddress);
+
+      return res.json({
+        success: true,
+        printer,
+        found: printer !== null
+      });
+
+    } catch (error) {
+      console.error('[API] Single IP scan failed:', error);
+      const appError = toAppError(error);
+      return sendErrorResponse(res, 500, appError.message);
+    }
+  });
+
+  /**
+   * GET /api/discovery/status
+   * Get current discovery status
+   */
+  router.get('/discovery/status', (_req: AuthenticatedRequest, res: Response) => {
+    return res.json({
+      success: true,
+      inProgress: discoveryService.isDiscoveryInProgress()
+    });
+  });
+
+  /**
+   * POST /api/discovery/cancel
+   * Cancel ongoing discovery
+   */
+  router.post('/discovery/cancel', (_req: AuthenticatedRequest, res: Response) => {
+    discoveryService.cancelDiscovery();
+    return res.json({
+      success: true,
+      message: 'Discovery cancelled'
+    } as StandardAPIResponse);
+  });
+}