@superdangerous/app-framework 4.9.0

package/src/desktop/bundler.ts

@@ -0,0 +1,271 @@
+/**
+ * Desktop Bundler Module
+ * Handles bundling Node.js backends for Electron desktop applications
+ */
+
+import * as esbuild from "esbuild";
+import {
+  ensureDir,
+  writeFile,
+  stat,
+  copy,
+  move,
+  remove,
+  writeJson,
+} from "../utils/fs-utils.js";
+import path from "path";
+import { execSync } from "child_process";
+import { createLogger } from "../core/index.js";
+import {
+  detectNativeModules,
+  copyNativeModules,
+  createNativeModuleLoader,
+} from "./native-modules.js";
+
+const logger = createLogger("DesktopBundler");
+
+export interface BundleOptions {
+  entryPoint: string;
+  outDir: string;
+  appName: string;
+  version: string;
+  platform?: "node" | "neutral";
+  target?: string;
+  format?: "cjs" | "esm";
+  minify?: boolean;
+  sourcemap?: boolean;
+  external?: string[];
+  env?: Record<string, string>;
+  resources?: {
+    config?: string;
+    data?: string[];
+  };
+  nativeModules?: {
+    autoDetect?: boolean;
+    modules?: string[];
+    rebuild?: boolean;
+  };
+}
+
+/**
+ * Bundle a Node.js backend for desktop deployment
+ */
+export async function bundleBackend(options: BundleOptions): Promise<void> {
+  const {
+    entryPoint,
+    outDir,
+    appName,
+    version,
+    platform = "node",
+    target = "node18",
+    format = "cjs",
+    minify = false,
+    sourcemap = false,
+    external = [],
+    env = {},
+    resources = {},
+  } = options;
+
+  logger.info(`Bundling backend for ${appName} v${version}`);
+
+  // Ensure output directory exists
+  await ensureDir(outDir);
+
+  // Default externals for Node.js
+  const defaultExternals = [
+    "fsevents", // Mac-specific, optional
+    "bufferutil", // Optional WebSocket performance
+    "utf-8-validate", // Optional WebSocket validation
+    "@superdangerous/app-framework/ui", // UI components not needed in backend
+    "serialport", // Optional serial port support
+    "@serialport/bindings-cpp", // Optional serial port bindings
+    "@aws-sdk/client-s3", // Optional AWS S3 support
+    "modbus-serial", // Optional Modbus communication
+  ];
+
+  // Build with esbuild
+  const result = await esbuild.build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    platform,
+    target,
+    outfile: path.join(outDir, "backend.js"),
+    format,
+    minify,
+    sourcemap,
+    external: [...defaultExternals, ...external],
+    define: {
+      "process.env.NODE_ENV": '"production"',
+      "process.env.DESKTOP_MODE": '"true"',
+      ...Object.entries(env).reduce(
+        (acc, [key, value]) => {
+          acc[`process.env.${key}`] = JSON.stringify(value);
+          return acc;
+        },
+        {} as Record<string, string>,
+      ),
+    },
+    loader: {
+      ".node": "file",
+      ".json": "json",
+    },
+    metafile: true,
+    logLevel: "info",
+  });
+
+  // Write metafile for analysis
+  await writeFile(
+    path.join(outDir, "backend-meta.json"),
+    JSON.stringify(result.metafile, null, 2),
+  );
+
+  // Create wrapper script
+  const wrapperScript = generateWrapperScript(appName, format);
+  await writeFile(path.join(outDir, "start-backend.js"), wrapperScript);
+
+  // Copy resources
+  if (resources.config) {
+    const configDest = path.join(outDir, "config");
+    await ensureDir(configDest);
+    await copy(resources.config, path.join(configDest, "app.json"));
+  }
+
+  if (resources.data) {
+    const dataDir = path.join(outDir, "data");
+    for (const dir of resources.data) {
+      await ensureDir(path.join(dataDir, dir));
+    }
+  }
+
+  // Handle native modules if configured
+  if (options.nativeModules) {
+    const projectDir = path.dirname(entryPoint);
+
+    // Detect native modules if requested
+    let nativeModulesList = options.nativeModules.modules || [];
+    if (options.nativeModules.autoDetect) {
+      const detected = await detectNativeModules(projectDir);
+      nativeModulesList = [...new Set([...nativeModulesList, ...detected])];
+      logger.info(`Detected native modules: ${nativeModulesList.join(", ")}`);
+    }
+
+    // Copy native modules to output directory
+    if (nativeModulesList.length > 0) {
+      await copyNativeModules({
+        modules: nativeModulesList,
+        sourceDir: projectDir,
+        targetDir: outDir,
+        rebuild: options.nativeModules.rebuild,
+      });
+
+      // Create native module loader
+      await createNativeModuleLoader(
+        path.join(outDir, "native-loader.js"),
+        nativeModulesList,
+      );
+
+      logger.info(`Copied ${nativeModulesList.length} native modules`);
+    }
+  }
+
+  // Get bundle size
+  const stats = await stat(path.join(outDir, "backend.js"));
+  const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+
+  logger.info(`✅ Backend bundled successfully!`);
+  logger.info(`   Bundle size: ${sizeMB} MB`);
+  logger.info(`   Location: ${outDir}/backend.js`);
+}
+
+/**
+ * Generate wrapper script for starting the bundled backend
+ */
+function generateWrapperScript(appName: string, format: "cjs" | "esm"): string {
+  return `#!/usr/bin/env node
+
+/**
+ * Desktop App Backend Wrapper for ${appName}
+ * Sets up environment and starts the bundled backend
+ */
+
+${format === "esm" ? "import { fileURLToPath } from 'url';" : ""}
+${format === "esm" ? "import { dirname, join } from 'path';" : "const path = require('path');"}
+
+${
+  format === "esm"
+    ? `
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+`
+    : ""
+}
+
+// Set environment variables
+process.env.NODE_ENV = process.env.NODE_ENV || 'production';
+process.env.DESKTOP_MODE = 'true';
+
+// Set data directory to app data location
+if (!process.env.DATA_DIR) {
+  // In production, this will be set by Electron
+  // For testing, use a local data directory
+  process.env.DATA_DIR = ${format === "esm" ? "join" : "path.join"}(__dirname, 'data');
+}
+
+// Note: Using console.log in wrapper script as it runs in production without logger
+console.log('Starting ${appName} Backend...');
+console.log('Data directory:', process.env.DATA_DIR);
+
+// Start the bundled backend
+${format === "cjs" ? "require('./backend.js');" : "import('./backend.js');"}
+`;
+}
+
+/**
+ * Bundle dependencies separately for better caching
+ */
+export async function bundleDependencies(
+  packageJsonPath: string,
+  outDir: string,
+): Promise<void> {
+  const fs = await import("fs");
+  const packageJson = JSON.parse(
+    await fs.promises.readFile(packageJsonPath, "utf8"),
+  );
+  const dependencies = packageJson.dependencies || {};
+
+  logger.info("Installing production dependencies...");
+
+  // Create temporary directory for dependencies
+  const tempDir = path.join(outDir, "temp");
+  await ensureDir(tempDir);
+
+  // Create minimal package.json
+  const minimalPackage = {
+    name: packageJson.name,
+    version: packageJson.version,
+    dependencies,
+  };
+
+  await writeJson(path.join(tempDir, "package.json"), minimalPackage);
+
+  // Install production dependencies
+  execSync("npm install --production --no-audit --no-fund", {
+    cwd: tempDir,
+    stdio: "inherit",
+  });
+
+  // Move node_modules to output directory
+  await move(
+    path.join(tempDir, "node_modules"),
+    path.join(outDir, "node_modules"),
+    { overwrite: true },
+  );
+
+  // Clean up temp directory
+  await remove(tempDir);
+}
+
+export default {
+  bundleBackend,
+  bundleDependencies,
+};

package/src/desktop/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Desktop Module Exports
+ * Provides all desktop-related utilities for Electron integration
+ */
+
+export * from "./bundler.js";
+export * from "./native-modules.js";
+
+// Re-export as namespace for convenience
+import * as bundler from "./bundler.js";
+import * as nativeModules from "./native-modules.js";
+
+export const Desktop = {
+  ...bundler,
+  ...nativeModules,
+};
+
+export default Desktop;

package/src/desktop/native-modules.ts

@@ -0,0 +1,289 @@
+/**
+ * Native Module Handler for Desktop Bundling
+ * Manages native Node.js modules that can't be bundled
+ */
+
+import {
+  ensureDir,
+  pathExists,
+  copy,
+  writeFile,
+  readFile,
+  readdir,
+  stat,
+} from "../utils/fs-utils.js";
+import path from "path";
+import { execSync } from "child_process";
+import { createLogger } from "../core/logger.js";
+const logger = createLogger("native-modules");
+
+export interface NativeModuleConfig {
+  /**
+   * List of native modules to copy to resources
+   */
+  modules: string[];
+
+  /**
+   * Source node_modules directory
+   */
+  sourceDir: string;
+
+  /**
+   * Target resources directory
+   */
+  targetDir: string;
+
+  /**
+   * Whether to rebuild native modules for target platform
+   */
+  rebuild?: boolean;
+
+  /**
+   * Electron version (if rebuilding for Electron)
+   */
+  electronVersion?: string;
+}
+
+/**
+ * Default native modules that commonly need special handling
+ */
+export const COMMON_NATIVE_MODULES = [
+  "serialport",
+  "@serialport/bindings-cpp",
+  "node-pty",
+  "bcrypt",
+  "better-sqlite3",
+  "canvas",
+  "sharp",
+  "fsevents",
+  "usb",
+  "node-hid",
+];
+
+/**
+ * Copy native modules to resources directory
+ */
+export async function copyNativeModules(
+  config: NativeModuleConfig,
+): Promise<void> {
+  const { modules, sourceDir, targetDir } = config;
+
+  // Ensure target directory exists
+  await ensureDir(path.join(targetDir, "node_modules"));
+
+  for (const moduleName of modules) {
+    const sourcePath = path.join(sourceDir, "node_modules", moduleName);
+    const targetPath = path.join(targetDir, "node_modules", moduleName);
+
+    if (await pathExists(sourcePath)) {
+      logger.info(`📦 Copying native module: ${moduleName}`);
+      await copy(sourcePath, targetPath);
+    } else {
+      logger.warn(`⚠️  Native module not found: ${moduleName}`);
+    }
+  }
+}
+
+/**
+ * Rebuild native modules for target platform
+ */
+export async function rebuildNativeModules(
+  targetDir: string,
+  electronVersion?: string,
+): Promise<void> {
+  logger.info("🔨 Rebuilding native modules...");
+
+  const cwd = targetDir;
+
+  if (electronVersion) {
+    // Rebuild for Electron
+    try {
+      execSync(`npx electron-rebuild -v ${electronVersion}`, {
+        cwd,
+        stdio: "inherit",
+      });
+    } catch (_error) {
+      logger.error("Failed to rebuild for Electron:", _error);
+      throw _error;
+    }
+  } else {
+    // Rebuild for Node.js
+    try {
+      execSync("npm rebuild", { cwd, stdio: "inherit" });
+    } catch (_error) {
+      logger.error("Failed to rebuild native modules:", _error);
+      throw _error;
+    }
+  }
+}
+
+/**
+ * Create a loader script that sets up paths for native modules
+ */
+export async function createNativeModuleLoader(
+  outputPath: string,
+  nativeModules: string[],
+): Promise<void> {
+  const loaderScript = `/**
+ * Native Module Loader
+ * Sets up require paths for native modules in desktop app
+ */
+
+const path = require('path');
+const Module = require('module');
+
+// Add native modules directory to Node module paths
+const nativeModulesPath = path.join(__dirname, 'node_modules');
+Module.globalPaths.push(nativeModulesPath);
+
+// Patch require to handle native modules
+const originalRequire = Module.prototype.require;
+const nativeModules = ${JSON.stringify(nativeModules)};
+
+Module.prototype.require = function(id) {
+  // Check if this is a native module
+  if (nativeModules.includes(id) || nativeModules.some(m => id.startsWith(m + '/'))) {
+    try {
+      // Try to load from native modules directory
+      return originalRequire.apply(this, [path.join(nativeModulesPath, id)]);
+    } catch (_error) {
+      // Fall back to original require
+      return originalRequire.apply(this, arguments);
+    }
+  }
+  
+  return originalRequire.apply(this, arguments);
+};
+
+// Export for use in main bundle
+module.exports = { nativeModulesPath };
+`;
+
+  await writeFile(outputPath, loaderScript, "utf8");
+}
+
+/**
+ * Check if a module is a native module
+ */
+export async function isNativeModule(moduleName: string): Promise<boolean> {
+  try {
+    const packageJsonPath = require.resolve(`${moduleName}/package.json`);
+    const content = await readFile(packageJsonPath, "utf8");
+    const packageJson = JSON.parse(content);
+
+    // Check for common indicators of native modules
+    return !!(
+      packageJson.gypfile ||
+      packageJson.binary ||
+      packageJson.scripts?.install ||
+      packageJson.scripts?.postinstall?.includes("node-gyp") ||
+      packageJson.dependencies?.["node-addon-api"] ||
+      packageJson.dependencies?.["nan"]
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect all native modules in a project
+ */
+export async function detectNativeModules(
+  projectDir: string,
+): Promise<string[]> {
+  const nodeModulesDir = path.join(projectDir, "node_modules");
+  const nativeModules: string[] = [];
+
+  if (!(await pathExists(nodeModulesDir))) {
+    return nativeModules;
+  }
+
+  const modules = await readdir(nodeModulesDir);
+
+  for (const moduleName of modules) {
+    if (moduleName.startsWith(".")) continue;
+
+    const modulePath = path.join(nodeModulesDir, moduleName);
+    const stats = await stat(modulePath);
+
+    if (stats.isDirectory()) {
+      if (moduleName.startsWith("@")) {
+        // Scoped package
+        const scopedModules = await readdir(modulePath);
+        for (const scopedModule of scopedModules) {
+          const fullName = `${moduleName}/${scopedModule}`;
+          if (await isNativeModule(fullName)) {
+            nativeModules.push(fullName);
+          }
+        }
+      } else {
+        // Regular package
+        if (await isNativeModule(moduleName)) {
+          nativeModules.push(moduleName);
+        }
+      }
+    }
+  }
+
+  return nativeModules;
+}
+
+/**
+ * Bundle configuration that handles native modules
+ */
+export interface BundleWithNativeModulesOptions {
+  entryPoint: string;
+  outputPath: string;
+  nativeModules?: string[];
+  autoDetect?: boolean;
+  rebuild?: boolean;
+  electronVersion?: string;
+}
+
+/**
+ * Create a bundle that properly handles native modules
+ */
+export async function bundleWithNativeModules(
+  options: BundleWithNativeModulesOptions,
+): Promise<void> {
+  const {
+    entryPoint,
+    outputPath,
+    autoDetect = true,
+    rebuild = false,
+    electronVersion,
+  } = options;
+
+  const projectDir = path.dirname(entryPoint);
+  const outputDir = path.dirname(outputPath);
+
+  // Detect or use provided native modules
+  let nativeModules = options.nativeModules || [];
+  if (autoDetect) {
+    const detected = await detectNativeModules(projectDir);
+    nativeModules = [...new Set([...nativeModules, ...detected])];
+    logger.info(`🔍 Detected native modules: ${nativeModules.join(", ")}`);
+  }
+
+  // Copy native modules
+  if (nativeModules.length > 0) {
+    await copyNativeModules({
+      modules: nativeModules,
+      sourceDir: projectDir,
+      targetDir: outputDir,
+    });
+
+    // Create loader script
+    await createNativeModuleLoader(
+      path.join(outputDir, "native-loader.js"),
+      nativeModules,
+    );
+
+    // Rebuild if requested
+    if (rebuild) {
+      await rebuildNativeModules(outputDir, electronVersion);
+    }
+  }
+
+  logger.info("✅ Native modules prepared for bundling");
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * SuperDangerous App Framework
+ * Main entry point for the TypeScript framework
+ */
+
+// Core exports
+export * from "./core/index.js";
+// API Response utilities are exported separately to avoid conflicts
+export {
+  sendSuccess,
+  sendError,
+  sendValidationError,
+  sendNotFound,
+  sendUnauthorized,
+  sendForbidden,
+  sendBadRequest,
+  sendCreated,
+  sendNoContent,
+  asyncHandler,
+  apiErrorHandler,
+  type ApiResponse,
+  type ApiErrorResponse,
+  type ApiSuccessResponse,
+} from "./core/apiResponse.js";
+
+// Service exports
+export * from "./services/index.js";
+
+// Middleware exports
+export * from "./middleware/index.js";
+export * from "./middleware/auth.js";
+export {
+  configureSession,
+  sessionUtils,
+  createRedisStore,
+} from "./middleware/session.js";
+export type { SessionConfig as FrameworkSessionConfig } from "./middleware/session.js";
+
+// Utility exports
+export * from "./utils/index.js";
+
+// Re-export commonly used items at top level
+export { createLogger, type Logger, type LogLevel } from "./core/index.js";
+export { StandardServer, createStandardServer } from "./core/StandardServer.js";
+export type { StandardServerConfig } from "./core/StandardServer.js";
+export {
+  StorageService,
+  getStorageService,
+  SecureFileHandler,
+  getSecureFileHandler,
+} from "./core/storageService.js";
+export {
+  createWebSocketServer,
+  getWebSocketServer,
+} from "./services/websocketServer.js";
+export { validate, schemas } from "./middleware/validation.js";
+
+// Testing utilities
+export {
+  TestServer,
+  createTestServer,
+  setupTestServer,
+  teardownTestServer,
+  getTestServer,
+} from "./testing/TestServer.js";
+export type { TestServerConfig } from "./testing/TestServer.js";
+
+// Standardized API routers
+export { default as logsRouter } from "./api/logsRouter.js";
+export type { LogEntry as RouterLogEntry, LogFile } from "./api/logsRouter.js";
+
+// Desktop integration exports
+export * from "./desktop/index.js";
+
+// System monitoring exports
+export { getSystemMonitor } from "./services/systemMonitor.js";
+export type {
+  SystemHealth,
+  CPUInfo,
+  MemoryInfo,
+  DiskInfo,
+  SystemInfo,
+  ProcessInfo,
+} from "./services/systemMonitor.js";
+
+// Health check exports
+export {
+  createHealthCheckRouter,
+  getHealthCheckService,
+  type SystemHealth as HealthStatus,
+  type SystemMetrics,
+  type HealthCheckOptions,
+  type CustomHealthCheck,
+  type HealthCheckResult,
+  type DependencyHealth,
+} from "./core/healthCheck.js";
+
+// WebSocket Manager exports
+
+// Configuration management - use SettingsService instead
+
+// Settings Schema exports - Consolidated implementation
+export {
+  createSettingsSchema,
+  flattenSettings,
+  unflattenSettings,
+  flattenSettingsValues,
+  unflattenSettingsValues,
+  getRestartRequiredSettings,
+  validateSettings,
+  validateSetting,
+  validateAllSettings,
+  getSettingByKey,
+  getDefaultSettingsValues,
+  evaluateFieldVisibility,
+  groupFields,
+  applyToStorageTransform,
+  applyFromStorageTransform,
+  createSettingsFormState,
+  Validators,
+  type SettingsSchema,
+  type SettingsCategory,
+  type SettingDefinition,
+  type SettingOption,
+  type SettingsFormState,
+  type SettingsValidationResult,
+} from "./settings/SettingsSchema.js";
+
+// Log Categories exports
+export {
+  LogLevels,
+  defaultLogViewerConfig,
+  parseLogEntry,
+  formatLogEntry,
+  calculateLogStats,
+  filterLogEntries,
+  type LogCategory,
+  type LogFilter,
+  type LogViewerConfig,
+  type LogEntry,
+  type LogStats,
+} from "./logging/LogCategories.js";