@W-19978113 Build Core Runtime Error Capture and Diagnostic Payload / Implement Error Handling System

package.json

@@ -16,6 +16,7 @@
     "@salesforce/lwc-dev-mobile-core": "4.0.0-alpha.13",
     "@salesforce/sf-plugins-core": "^11.2.4",
     "axios": "^1.12.2",
+    "express": "^5.1.0",
     "glob": "^10.4.5",
     "lwc": "~8.23.0",
     "node-fetch": "^3.3.2",
@@ -27,6 +28,7 @@
     "@salesforce/cli-plugins-testkit": "^5.3.41",
     "@salesforce/dev-scripts": "^11.0.4",
     "@salesforce/plugin-command-reference": "^3.1.74",
+    "@types/express": "^5.0.3",
     "@types/node-fetch": "^2.6.13",
     "@types/xml2js": "^0.4.14",
     "@typescript-eslint/eslint-plugin": "^6.21.0",

src/lwc-dev-server/errorHttpServer.ts

@@ -0,0 +1,215 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Server } from 'node:http';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import express, { Express } from 'express';
+import { Logger } from '@salesforce/core';
+import { ErrorStore } from './errorStore.js';
+import { createCombinedErrorMiddleware, createErrorCORSMiddleware } from './errorMiddleware.js';
+
+/**
+ * Configuration for the standalone error capture HTTP server
+ */
+export type ErrorServerConfig = {
+  /** Port for the error capture server */
+  port: number;
+  /** Error store instance */
+  errorStore: ErrorStore;
+  /** Logger instance */
+  logger: Logger;
+  /** Project root directory */
+  projectRoot: string;
+  /** Whether to log errors to console */
+  logToConsole?: boolean;
+  /** Whether to bind to localhost only (recommended for security) */
+  localhostOnly?: boolean;
+};
+
+/**
+ * Standalone HTTP server for error capture endpoints.
+ *
+ * This server runs independently of the LWC dev server and provides
+ * HTTP endpoints for error reporting, querying, and management.
+ *
+ * Endpoints:
+ * - POST /_dev/errors - Capture error reports
+ * - GET /_dev/errors - Query stored errors (with filters)
+ * - DELETE /_dev/errors - Clear all errors
+ * - GET /_dev/errors/stats - Get error statistics
+ *
+ * @example
+ * ```typescript
+ * const errorServer = await startErrorCaptureServer({
+ *   port: 8082,
+ *   errorStore: getErrorStore(),
+ *   logger,
+ *   projectRoot: '/path/to/project',
+ * });
+ *
+ * // Later...
+ * await errorServer.stop();
+ * ```
+ */
+export class ErrorCaptureServer {
+  private app: Express;
+  private server: Server | null = null;
+  private config: ErrorServerConfig;
+
+  public constructor(config: ErrorServerConfig) {
+    this.config = config;
+    this.app = express();
+    this.setupMiddleware();
+  }
+
+  /**
+   * Start the error capture server
+   */
+  public async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const { port, localhostOnly = true, logger } = this.config;
+
+      try {
+        // Bind to localhost only for security (unless explicitly disabled)
+        const host = localhostOnly ? 'localhost' : '0.0.0.0';
+
+        this.server = this.app.listen(port, host, () => {
+          logger.info(`[ErrorCapture] Error capture server started at http://${host}:${port}`);
+          logger.info('[ErrorCapture] Available endpoints:');
+          logger.info('[ErrorCapture]   POST   /_dev/errors       - Capture error reports');
+          logger.info(
+            '[ErrorCapture]   GET    /_dev/errors       - Query errors (supports ?component=, ?severity=, ?limit=)'
+          );
+          logger.info('[ErrorCapture]   DELETE /_dev/errors       - Clear all errors');
+          logger.info('[ErrorCapture]   GET    /_dev/errors/stats - Get statistics');
+          logger.info('[ErrorCapture]   GET    /_dev/health       - Health check');
+          resolve();
+        });
+
+        this.server.on('error', (err: NodeJS.ErrnoException) => {
+          if (err.code === 'EADDRINUSE') {
+            logger.error(`[ErrorCapture] Port ${port} is already in use. Please use a different port.`);
+            reject(new Error(`Port ${port} is already in use`));
+          } else {
+            logger.error(`[ErrorCapture] Server error: ${err.message}`);
+            reject(err);
+          }
+        });
+      } catch (err) {
+        logger.error(
+          `[ErrorCapture] Failed to start error capture server: ${err instanceof Error ? err.message : String(err)}`
+        );
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Stop the error capture server
+   */
+  public async stop(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.server) {
+        resolve();
+        return;
+      }
+
+      this.server.close((err) => {
+        if (err) {
+          this.config.logger.error(`[ErrorCapture] Error stopping server: ${err.message}`);
+          reject(err);
+        } else {
+          this.config.logger.info('[ErrorCapture] Error capture server stopped');
+          this.server = null;
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Get the underlying Express app (for testing)
+   */
+  public getApp(): Express {
+    return this.app;
+  }
+
+  /**
+   * Get the server instance (for testing)
+   */
+  public getServer(): Server | null {
+    return this.server;
+  }
+
+  /**
+   * Check if server is running
+   */
+  public isRunning(): boolean {
+    return this.server !== null && this.server.listening;
+  }
+
+  /**
+   * Set up Express middleware
+   */
+  private setupMiddleware(): void {
+    const { errorStore, logger, projectRoot, logToConsole = true } = this.config;
+
+    // Parse JSON request bodies
+    this.app.use(express.json({ limit: '10mb' }));
+
+    // Enable CORS for error endpoints
+    this.app.use(createErrorCORSMiddleware());
+
+    // Add combined error middleware
+    const errorMiddleware = createCombinedErrorMiddleware({
+      errorStore,
+      logger,
+      projectRoot,
+      logToConsole,
+    });
+    this.app.use(errorMiddleware);
+
+    // Health check endpoint
+    this.app.get('/_dev/health', (_req, res) => {
+      res.json({
+        status: 'ok',
+        service: 'error-capture',
+        uptime: process.uptime(),
+        errors: errorStore.getErrorCount(),
+      });
+    });
+
+    // Catch-all for unknown routes
+    this.app.use((_req, res) => {
+      res.status(404).json({
+        error: 'Not Found',
+        message: 'Endpoint not found. Available endpoints: POST/GET/DELETE /_dev/errors, GET /_dev/errors/stats',
+      });
+    });
+  }
+}
+
+/**
+ * Convenience function to start an error capture server
+ *
+ * @param config - Server configuration
+ * @returns Running ErrorCaptureServer instance
+ */
+export async function startErrorCaptureServer(config: ErrorServerConfig): Promise<ErrorCaptureServer> {
+  const server = new ErrorCaptureServer(config);
+  await server.start();
+  return server;
+}