@superdangerous/app-framework 4.9.0

package/src/testing/TestServer.ts

@@ -0,0 +1,312 @@
+/**
+ * Test Server Utility
+ * Provides standardized test server management for all SuperDangerous applications
+ */
+
+import { spawn, ChildProcess } from "child_process";
+import { execSync } from "child_process";
+import { createLogger } from "../core/index.js";
+
+let logger: any; // Will be initialized when needed
+
+function ensureLogger() {
+  if (!logger) {
+    logger = createLogger("TestServer");
+  }
+  return logger;
+}
+
+export interface TestServerConfig {
+  /** Path to the application entry point */
+  entryPoint: string;
+  /** Port to run the server on */
+  port: number;
+  /** API base URL */
+  apiBase?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Timeout for server startup (ms) */
+  startupTimeout?: number;
+  /** Health check endpoint */
+  healthEndpoint?: string;
+  /** Whether to suppress server output */
+  silent?: boolean;
+}
+
+export class TestServer {
+  private process: ChildProcess | null = null;
+  private config: Required<TestServerConfig>;
+  private startPromise: Promise<void> | null = null;
+  public port: number;
+
+  constructor(config: TestServerConfig) {
+    this.port = config.port;
+    this.config = {
+      apiBase: `http://localhost:${config.port}`,
+      env: {},
+      startupTimeout: 30000,
+      healthEndpoint: "/api/health",
+      silent: true,
+      ...config,
+    };
+  }
+
+  /**
+   * Clean up any existing processes on the port
+   */
+  private cleanupPort(): void {
+    try {
+      if (process.platform === "win32") {
+        // Windows: Find and kill process using the port
+        execSync(
+          `netstat -ano | findstr :${this.config.port} | findstr LISTENING`,
+          { stdio: "ignore" },
+        );
+        const result = execSync(
+          `netstat -ano | findstr :${this.config.port} | findstr LISTENING`,
+        ).toString();
+        const lines = result.split("\n");
+        for (const line of lines) {
+          const parts = line.trim().split(/\s+/);
+          const pid = parts[parts.length - 1];
+          if (pid && pid !== "0") {
+            execSync(`taskkill /F /PID ${pid}`, { stdio: "ignore" });
+          }
+        }
+      } else {
+        // Unix-like: Use lsof to find and kill process
+        execSync(
+          `lsof -ti:${this.config.port} | xargs kill -9 2>/dev/null || true`,
+          { stdio: "ignore" },
+        );
+      }
+    } catch (_error) {
+      // Port might already be free, ignore errors
+    }
+  }
+
+  /**
+   * Wait for the server to be ready
+   */
+  private async waitForServer(): Promise<void> {
+    const startTime = Date.now();
+    const { apiBase, healthEndpoint, startupTimeout } = this.config;
+    const healthUrl = `${apiBase}${healthEndpoint}`;
+
+    if (!this.config.silent) {
+      console.log(`Waiting for server at ${healthUrl}...`);
+    }
+
+    while (Date.now() - startTime < startupTimeout) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 1000);
+
+        const response = await fetch(healthUrl, {
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (response.ok) {
+          if (!this.config.silent) {
+            console.log(`Server is ready at ${healthUrl}`);
+          }
+          return; // Server is ready
+        }
+      } catch (_error) {
+        // Server not ready yet
+      }
+
+      // Check if process has exited
+      if (this.process && this.process.exitCode !== null) {
+        throw new Error(
+          `Server process exited with code ${this.process.exitCode}`,
+        );
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    throw new Error(`Server failed to start within ${startupTimeout}ms`);
+  }
+
+  /**
+   * Start the test server
+   */
+  async start(): Promise<void> {
+    // Return existing promise if already starting
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+
+    // Already running
+    if (this.process) {
+      return;
+    }
+
+    this.startPromise = this._start();
+    return this.startPromise;
+  }
+
+  private async _start(): Promise<void> {
+    // Clean up any existing processes
+    this.cleanupPort();
+
+    // Determine command based on entry point extension
+    const { entryPoint } = this.config;
+    const isTypeScript = entryPoint.endsWith(".ts");
+    const command = isTypeScript ? "npx" : "node";
+    const args = isTypeScript ? ["tsx", entryPoint] : [entryPoint];
+
+    // Start the server process
+    this.process = spawn(command, args, {
+      env: {
+        ...process.env,
+        ...this.config.env,
+        NODE_ENV: "test",
+        PORT: String(this.config.port),
+        API_PORT: String(this.config.port),
+        SILENT_STARTUP: "1",
+      },
+      stdio: this.config.silent ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+
+    // Handle process output if not silent
+    if (this.config.silent && this.process.stdout && this.process.stderr) {
+      this.process.stdout.on("data", (data) => {
+        const output = data.toString();
+        // Only log errors or important messages
+        if (output.includes("ERROR") || output.includes("WARN")) {
+          ensureLogger().debug(`Server output: ${output}`);
+        }
+      });
+
+      this.process.stderr.on("data", (data) => {
+        ensureLogger().error(`Server error: ${data}`);
+      });
+    }
+
+    // Handle process exit
+    this.process.on("exit", (code) => {
+      if (code !== 0 && code !== null) {
+        ensureLogger().error(`Server process exited with code ${code}`);
+      }
+    });
+
+    // Wait for server to be ready
+    await this.waitForServer();
+    ensureLogger().debug(`Test server started on port ${this.config.port}`);
+  }
+
+  /**
+   * Stop the test server
+   */
+  async stop(): Promise<void> {
+    if (!this.process) {
+      return;
+    }
+
+    return new Promise((resolve) => {
+      if (!this.process) {
+        resolve();
+        return;
+      }
+
+      const cleanup = () => {
+        this.process = null;
+        this.startPromise = null;
+        resolve();
+      };
+
+      // Set a timeout for graceful shutdown
+      const killTimeout = setTimeout(() => {
+        if (this.process) {
+          this.process.kill("SIGKILL");
+        }
+        cleanup();
+      }, 5000);
+
+      this.process.on("exit", () => {
+        clearTimeout(killTimeout);
+        cleanup();
+      });
+
+      // Try graceful shutdown first
+      this.process.kill("SIGTERM");
+    });
+  }
+
+  /**
+   * Get the API base URL
+   */
+  getApiBase(): string {
+    return this.config.apiBase;
+  }
+
+  /**
+   * Make a request to the test server
+   */
+  async request(endpoint: string, options: any = {}): Promise<any> {
+    const url = `${this.config.apiBase}${endpoint}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+    });
+
+    const text = await response.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+
+    return {
+      status: response.status,
+      ok: response.ok,
+      data,
+      response,
+    };
+  }
+}
+
+/**
+ * Create a test server instance
+ */
+export function createTestServer(config: TestServerConfig): TestServer {
+  return new TestServer(config);
+}
+
+/**
+ * Global test server instance for Jest
+ */
+let globalTestServer: TestServer | null = null;
+
+/**
+ * Setup function for Jest beforeAll
+ */
+export async function setupTestServer(config: TestServerConfig): Promise<void> {
+  globalTestServer = new TestServer(config);
+  await globalTestServer.start();
+}
+
+/**
+ * Teardown function for Jest afterAll
+ */
+export async function teardownTestServer(): Promise<void> {
+  if (globalTestServer) {
+    await globalTestServer.stop();
+    globalTestServer = null;
+  }
+}
+
+/**
+ * Get the global test server instance
+ */
+export function getTestServer(): TestServer | null {
+  return globalTestServer;
+}

package/src/types/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared TypeScript Type Definitions
+ */
+
+/**
+ * Field validation error detail
+ */
+export interface FieldValidationError {
+  field: string;
+  message: string;
+}
+
+/**
+ * Standardized API response structure for all applications
+ * Supports both legacy string errors and new structured errors
+ * @template T - The type of the data payload
+ */
+export interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  error?:
+    | string
+    | {
+        code: string;
+        message: string;
+        details?: any;
+        stack?: string; // Only in development
+      };
+  message?: string; // Optional success message
+  errors?: FieldValidationError[]; // For validation errors
+  metadata?: {
+    timestamp: string;
+    version?: string;
+    requestId?: string;
+    pagination?: {
+      page: number;
+      limit: number;
+      total: number;
+      hasMore: boolean;
+    };
+  };
+  timestamp?: string; // Legacy field for backward compatibility
+}
+
+/**
+ * Legacy simple error format (deprecated - for backward compatibility)
+ * @deprecated Use structured error object instead
+ */
+export interface ApiResponseLegacy<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+  timestamp?: string;
+}
+
+/**
+ * Configuration options
+ */
+export interface ConfigOptions {
+  configPath?: string;
+  defaultConfig?: any;
+  watchChanges?: boolean;
+}
+
+/**
+ * Network interface information
+ */
+export interface NetworkInterface {
+  name: string;
+  address: string;
+  family: "IPv4" | "IPv6";
+  internal: boolean;
+  mac?: string;
+}
+
+/**
+ * Update check result
+ */
+export interface UpdateCheckResult {
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion?: string;
+  releaseUrl?: string;
+  releaseNotes?: string;
+  publishedAt?: string;
+}
+
+/**
+ * WebSocket client information
+ */
+export interface ClientInfo {
+  id: string;
+  connectedAt: Date;
+  lastActivity: Date;
+  subscriptions: Set<string>;
+}
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+  info: (...args: any[]) => void;
+  error: (...args: any[]) => void;
+  warn: (...args: any[]) => void;
+  debug: (...args: any[]) => void;
+}
+
+/**
+ * WebSocket message types
+ */
+export interface WebSocketMessage {
+  type: string;
+  data: any;
+}
+
+export interface SimulatorUpdateMessage extends WebSocketMessage {
+  type: "simulator:started" | "simulator:stopped" | "simulator:data";
+  data: Simulator;
+}
+
+export interface TemplateUpdateMessage extends WebSocketMessage {
+  type: "template:created" | "template:updated" | "template:deleted";
+  data: Template;
+}
+
+export interface DataUpdateMessage extends WebSocketMessage {
+  type: "data:update";
+  data: {
+    simulatorId: string;
+    values: Record<string, any>;
+  };
+}
+
+export interface Simulator {
+  id: string;
+  name: string;
+  status: string;
+  [key: string]: any;
+}
+
+export interface Template {
+  id: string;
+  name: string;
+  [key: string]: any;
+}
+
+export interface AppConfig {
+  [key: string]: any;
+}
+
+export interface ValidationError extends Error {
+  details?: any[];
+}

package/src/utils/appPaths.ts

@@ -0,0 +1,196 @@
+import os from "os";
+import path from "path";
+import { mkdirSync } from "fs";
+
+/**
+ * Get the appropriate data directory for the application.
+ *
+ * In desktop app mode (Electron):
+ * - macOS: ~/Library/Application Support/{appId}
+ * - Windows: %APPDATA%/{appName}
+ * - Linux: ~/.local/share/{appName}
+ *
+ * In development or web mode:
+ * - Uses project root ./data directory
+ *
+ * @param appId - The application identifier (e.g., 'com.superdangerous.app-name')
+ * @param appName - The application name (e.g., 'app-name')
+ * @returns The absolute path to the application data directory
+ */
+export function getAppDataPath(appId: string, appName: string): string {
+  // Check if running in a desktop app environment
+  const isElectron =
+    process.versions?.electron || process.env.ELECTRON_RUNNING === "true";
+  const isDevelopment = process.env.NODE_ENV === "development";
+
+  // In development mode, always use local paths unless explicitly forced
+  const isDesktopApp = !isDevelopment && isElectron;
+
+  if (isDesktopApp) {
+    // Use platform-specific app data directories
+    const platform = process.platform;
+    const homeDir = os.homedir();
+    let appDataDir: string;
+
+    switch (platform) {
+      case "darwin": // macOS
+        appDataDir = path.join(
+          homeDir,
+          "Library",
+          "Application Support",
+          appId,
+        );
+        break;
+      case "win32": // Windows
+        appDataDir = path.join(
+          process.env.APPDATA || path.join(homeDir, "AppData", "Roaming"),
+          appName,
+        );
+        break;
+      default: // Linux and others
+        appDataDir = path.join(
+          process.env.XDG_DATA_HOME || path.join(homeDir, ".local", "share"),
+          appName,
+        );
+        break;
+    }
+
+    // Ensure the directory exists
+    mkdirSync(appDataDir, { recursive: true });
+    return appDataDir;
+  }
+
+  // In development or web mode, use the project root ./data directory
+  const dataDir = path.join(process.cwd(), "data");
+  mkdirSync(dataDir, { recursive: true });
+  return dataDir;
+}
+
+/**
+ * Get the full path for a data file within the application data directory.
+ *
+ * @param filename - The name of the file
+ * @param appId - The application identifier
+ * @param appName - The application name
+ * @returns The absolute path to the file
+ */
+export function getDataFilePath(
+  filename: string,
+  appId: string,
+  appName: string,
+): string {
+  return path.join(getAppDataPath(appId, appName), filename);
+}
+
+/**
+ * Get the logs directory path for the application.
+ *
+ * @param appId - The application identifier
+ * @param appName - The application name
+ * @returns The absolute path to the logs directory
+ */
+export function getLogsPath(appId: string, appName: string): string {
+  const logsDir = path.join(getAppDataPath(appId, appName), "logs");
+  mkdirSync(logsDir, { recursive: true });
+  return logsDir;
+}
+
+/**
+ * Get the configuration directory path for the application.
+ *
+ * @param appId - The application identifier
+ * @param appName - The application name
+ * @returns The absolute path to the config directory
+ */
+export function getConfigPath(appId: string, appName: string): string {
+  const configDir = path.join(getAppDataPath(appId, appName), "config");
+  mkdirSync(configDir, { recursive: true });
+  return configDir;
+}
+
+/**
+ * Get the cache directory path for the application.
+ *
+ * @param appId - The application identifier
+ * @param appName - The application name
+ * @returns The absolute path to the cache directory
+ */
+export function getCachePath(appId: string, appName: string): string {
+  const cacheDir = path.join(getAppDataPath(appId, appName), "cache");
+  mkdirSync(cacheDir, { recursive: true });
+  return cacheDir;
+}
+
+/**
+ * Check if the application is running in desktop mode (Electron).
+ *
+ * @returns True if running as a desktop app, false otherwise
+ */
+export function isDesktopApp(): boolean {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  const isElectron =
+    !!process.versions?.electron || process.env.ELECTRON_RUNNING === "true";
+
+  // In development mode, consider it a desktop app only if explicitly set
+  return !isDevelopment && isElectron;
+}
+
+/**
+ * Get platform-specific user documents directory.
+ *
+ * @returns The path to the user's documents directory
+ */
+export function getDocumentsPath(): string {
+  const platform = process.platform;
+  const homeDir = os.homedir();
+
+  switch (platform) {
+    case "darwin": // macOS
+    case "linux":
+      return path.join(homeDir, "Documents");
+    case "win32": // Windows
+      return path.join(homeDir, "Documents");
+    default:
+      return homeDir;
+  }
+}
+
+/**
+ * Get platform-specific user desktop directory.
+ *
+ * @returns The path to the user's desktop directory
+ */
+export function getDesktopPath(): string {
+  const platform = process.platform;
+  const homeDir = os.homedir();
+
+  switch (platform) {
+    case "darwin": // macOS
+    case "linux":
+      return path.join(homeDir, "Desktop");
+    case "win32": // Windows
+      return path.join(homeDir, "Desktop");
+    default:
+      return homeDir;
+  }
+}
+
+/**
+ * Get platform-specific user downloads directory.
+ *
+ * @returns The path to the user's downloads directory
+ */
+export function getDownloadsPath(): string {
+  const platform = process.platform;
+  const homeDir = os.homedir();
+
+  switch (platform) {
+    case "darwin": // macOS
+    case "linux":
+      return path.join(homeDir, "Downloads");
+    case "win32": // Windows
+      return path.join(homeDir, "Downloads");
+    default:
+      return homeDir;
+  }
+}