@superdangerous/app-framework 4.9.0

package/src/utils/fs-utils.ts

@@ -0,0 +1,130 @@
+/**
+ * File system utilities to replace fs-extra with native Node.js fs
+ * Provides cross-platform compatibility without ESM issues
+ */
+
+import fs from "fs/promises";
+import { createReadStream, createWriteStream } from "fs";
+import path from "path";
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export async function ensureDir(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+/**
+ * Check if a path exists
+ */
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy a file or directory
+ */
+export async function copy(src: string, dest: string): Promise<void> {
+  const stats = await fs.stat(src);
+
+  if (stats.isDirectory()) {
+    await ensureDir(dest);
+    const entries = await fs.readdir(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        await copy(srcPath, destPath);
+      } else {
+        await fs.copyFile(srcPath, destPath);
+      }
+    }
+  } else {
+    await fs.copyFile(src, dest);
+  }
+}
+
+/**
+ * Move a file or directory
+ */
+export async function move(
+  src: string,
+  dest: string,
+  options?: { overwrite?: boolean },
+): Promise<void> {
+  const { overwrite = true } = options || {};
+
+  if (!overwrite && (await pathExists(dest))) {
+    throw new Error(`Destination already exists: ${dest}`);
+  }
+
+  try {
+    await fs.rename(src, dest);
+  } catch (error: any) {
+    // If cross-device move, copy then delete
+    if (error.code === "EXDEV") {
+      await copy(src, dest);
+      await fs.rm(src, { recursive: true, force: true });
+    } else {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Remove a file or directory
+ */
+export async function remove(filePath: string): Promise<void> {
+  await fs.rm(filePath, { recursive: true, force: true });
+}
+
+/**
+ * Read a JSON file
+ */
+export async function readJson(filePath: string): Promise<any> {
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+
+/**
+ * Write a JSON file
+ */
+export async function writeJson(
+  filePath: string,
+  data: any,
+  options?: { spaces?: number },
+): Promise<void> {
+  const { spaces = 2 } = options || {};
+  const content = JSON.stringify(data, null, spaces);
+  await fs.writeFile(filePath, content, "utf8");
+}
+
+/**
+ * Empty a directory without removing it
+ */
+export async function emptyDir(dir: string): Promise<void> {
+  if (await pathExists(dir)) {
+    const entries = await fs.readdir(dir);
+    for (const entry of entries) {
+      await remove(path.join(dir, entry));
+    }
+  } else {
+    await ensureDir(dir);
+  }
+}
+
+// Re-export native fs methods that don't need replacement
+export { fs };
+export { createReadStream, createWriteStream };
+export const readFile = fs.readFile.bind(fs);
+export const writeFile = fs.writeFile.bind(fs);
+export const readdir = fs.readdir.bind(fs);
+export const stat = fs.stat.bind(fs);
+export const unlink = fs.unlink;

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Utilities Module Exports
+ */
+
+export { default as startupLogger } from "./startupLogger.js";
+export * from "../core/apiResponse.js";
+export {
+  displayStartupBanner,
+  displayMinimalStartup,
+} from "./startupBanner.js";
+export type { StartupBannerOptions } from "./startupBanner.js";
+export { loadStandardConfig, getDefaultPorts } from "./standardConfig.js";
+export type { StandardAppConfig } from "./standardConfig.js";
+export * from "./appPaths.js";
+export * as fsUtils from "./fs-utils.js";

package/src/utils/standardConfig.ts

@@ -0,0 +1,178 @@
+/**
+ * Standard Configuration Loader
+ * Provides consistent config loading across all SuperDangerous applications
+ */
+
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+
+export interface StandardAppConfig {
+  app: {
+    name: string;
+    version: string;
+    title: string;
+    description?: string;
+  };
+  server: {
+    port: number;
+    host: string;
+    webPort?: number;
+    websocketPort?: number;
+  };
+  ui?: {
+    theme?: "light" | "dark";
+    branding?: {
+      logo?: string;
+      primaryColor?: string;
+      secondaryColor?: string;
+    };
+  };
+  logging?: {
+    level?: string;
+    directory?: string;
+    file_pattern?: string;
+    maxSize?: string;
+    maxFiles?: string;
+    console_level?: string;
+  };
+  desktop?: {
+    enabled: boolean;
+    window?: {
+      width?: number;
+      height?: number;
+      minWidth?: number;
+      minHeight?: number;
+    };
+  };
+  defaults?: {
+    timeout?: number;
+    retryAttempts?: number;
+  };
+  [key: string]: any; // Allow app-specific config
+}
+
+/**
+ * Load application configuration with environment variable overrides
+ */
+export function loadStandardConfig(dirname: string): StandardAppConfig {
+  // Load package.json for defaults
+  const packageJsonPath = path.join(dirname, "../package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+  // Load app.json config if it exists
+  const configPath = path.join(dirname, "../data/config/app.json");
+  let appConfig: any = {};
+
+  if (existsSync(configPath)) {
+    appConfig = JSON.parse(readFileSync(configPath, "utf-8"));
+  }
+
+  // Normalize config structure (handle different formats)
+  const normalizedConfig: StandardAppConfig = {
+    app: {
+      name:
+        process.env.APP_NAME ||
+        appConfig.app?.name ||
+        packageJson.name ||
+        "SuperDangerous App",
+      version: appConfig.app?.version || packageJson.version || "1.0.0",
+      title:
+        process.env.APP_TITLE ||
+        appConfig.app?.title ||
+        appConfig.app_title || // Legacy support
+        packageJson.displayName || // Some packages use displayName
+        packageJson.name
+          ?.replace(/@[^/]+\//, "")
+          .replace(/-/g, " ")
+          .replace(/\b\w/g, (l: string) => l.toUpperCase()) ||
+        "SuperDangerous Application",
+      description:
+        process.env.APP_DESCRIPTION ||
+        appConfig.app?.description ||
+        packageJson.description,
+    },
+    server: {
+      port: Number(
+        process.env.PORT ||
+          process.env.API_PORT ||
+          appConfig.server?.port ||
+          appConfig.server?.api?.port ||
+          appConfig.api?.port ||
+          8080,
+      ),
+      host:
+        process.env.HOST ||
+        appConfig.server?.host ||
+        appConfig.server?.api?.host ||
+        appConfig.api?.host ||
+        "0.0.0.0",
+      webPort: Number(
+        process.env.WEB_PORT ||
+          appConfig.server?.webPort ||
+          appConfig.server?.web?.port ||
+          appConfig.webPort ||
+          5173,
+      ),
+      websocketPort: Number(
+        process.env.WEBSOCKET_PORT ||
+          appConfig.server?.websocketPort ||
+          appConfig.server?.websocket?.port ||
+          appConfig.webSocketPort ||
+          appConfig.server?.port ||
+          appConfig.api?.port,
+      ),
+    },
+    ui: appConfig.ui || {},
+    logging: {
+      level: process.env.LOG_LEVEL || appConfig.logging?.level || "INFO",
+      directory: appConfig.logging?.directory || "logs",
+      file_pattern: appConfig.logging?.file_pattern || "app.log",
+      maxSize: appConfig.logging?.maxSize || "20m",
+      maxFiles: appConfig.logging?.maxFiles || "14d",
+      console_level:
+        process.env.CONSOLE_LOG_LEVEL ||
+        appConfig.logging?.console_level ||
+        "INFO",
+    },
+    desktop: {
+      enabled:
+        process.env.DESKTOP === "true" || appConfig.desktop?.enabled || false,
+      ...appConfig.desktop,
+    },
+    defaults: appConfig.defaults || {
+      timeout: 5000,
+      retryAttempts: 3,
+    },
+  };
+
+  // Merge in any app-specific config
+  Object.keys(appConfig).forEach((key) => {
+    if (
+      ![
+        "app",
+        "server",
+        "api",
+        "ui",
+        "logging",
+        "desktop",
+        "defaults",
+      ].includes(key)
+    ) {
+      normalizedConfig[key] = appConfig[key];
+    }
+  });
+
+  return normalizedConfig;
+}
+
+/**
+ * Get default ports for an application
+ * Applications can override these by providing their own configuration
+ */
+export function getDefaultPorts(_appName: string): {
+  api: number;
+  web: number;
+} {
+  // Return sensible defaults - applications should define their own ports
+  return { api: 8080, web: 3000 };
+}

package/src/utils/startupBanner.ts

@@ -0,0 +1,287 @@
+/**
+ * Standardized Startup Banner for SuperDangerous Applications
+ */
+
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+
+// Force colors to ensure consistent output
+chalk.level = 3; // Full color support
+
+// Get framework version dynamically
+function getFrameworkVersion(): string {
+  // Try multiple strategies to find the framework version
+  const strategies = [
+    // Strategy 1: Check if we're in the framework itself (during development)
+    () => {
+      const localPkg = path.join(__dirname, "../../package.json");
+      if (fs.existsSync(localPkg)) {
+        const pkg = JSON.parse(fs.readFileSync(localPkg, "utf-8"));
+        if (pkg.name === "@superdangerous/app-framework") {
+          return pkg.version;
+        }
+      }
+      return null;
+    },
+    // Strategy 2: Check node_modules in current working directory
+    () => {
+      const nodeModulesPath = path.join(
+        process.cwd(),
+        "node_modules",
+        "@superdangerous",
+        "app-framework",
+        "package.json",
+      );
+      if (fs.existsSync(nodeModulesPath)) {
+        const pkg = JSON.parse(fs.readFileSync(nodeModulesPath, "utf-8"));
+        return pkg.version;
+      }
+      return null;
+    },
+    // Strategy 3: Try require.resolve to find the module
+    () => {
+      try {
+        const pkgPath = require.resolve(
+          "@superdangerous/app-framework/package.json",
+          { paths: [process.cwd()] },
+        );
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        return pkg.version;
+      } catch {
+        return null;
+      }
+    },
+  ];
+
+  for (const strategy of strategies) {
+    try {
+      const version = strategy();
+      if (version) return version;
+    } catch {
+      // Try next strategy
+    }
+  }
+
+  return "unknown";
+}
+
+const version = getFrameworkVersion();
+
+export interface BannerOptions {
+  appName: string;
+  appVersion: string;
+  environment?: string;
+  port?: number;
+  additionalInfo?: string[];
+  showTips?: boolean;
+  showCredits?: boolean;
+  color?: "blue" | "green" | "yellow" | "red";
+}
+
+export interface StartupBannerOptions extends BannerOptions {
+  appName: string;
+  appVersion: string;
+  packageName?: string; // Optional package name
+  description?: string;
+  port: number; // API port
+  webPort?: number; // Optional separate web UI port
+  webSocketPort?: number; // Optional WebSocket port
+  environment?: string;
+  startTime?: number;
+}
+
+/**
+ * Display a standardized startup banner for SuperDangerous applications
+ * All apps should use this exact same format for consistency
+ */
+export function displayStartupBanner(options: StartupBannerOptions): void {
+  const {
+    appName,
+    appVersion,
+    description,
+    port,
+    webPort, // Use separate web port if provided
+    webSocketPort, // WebSocket port
+    environment = process.env.NODE_ENV || "development",
+    startTime,
+  } = options;
+
+  const width = 50; // Reduced width to match horizontal dividers
+  const border = "─".repeat(width); // Full width for top/bottom borders
+
+  // Calculate startup time if provided
+  const startupTime = startTime
+    ? `${((Date.now() - startTime) / 1000).toFixed(1)}s`
+    : "0.0s";
+
+  // Helper to create a line with proper padding
+  const makeLine = (
+    content: string,
+    align: "center" | "left" = "center",
+  ): string => {
+    // eslint-disable-next-line no-control-regex
+    const visibleLength = content.replace(/\x1b\[[0-9;]*m/g, "").length; // Strip ANSI codes for length calculation
+    if (align === "center") {
+      const leftPad = Math.max(0, Math.floor((width - visibleLength) / 2));
+      const rightPad = Math.max(0, width - visibleLength - leftPad);
+      return (
+        chalk.gray("│") +
+        " ".repeat(leftPad) +
+        content +
+        " ".repeat(rightPad) +
+        chalk.gray("│")
+      );
+    } else {
+      const padding = Math.max(0, width - visibleLength);
+      return chalk.gray("│") + content + " ".repeat(padding) + chalk.gray("│");
+    }
+  };
+
+  // Helper to wrap text
+  const wrapText = (text: string, maxWidth: number): string[] => {
+    const words = text.split(" ");
+    const lines: string[] = [];
+    let currentLine = "";
+
+    for (const word of words) {
+      if ((currentLine + " " + word).trim().length <= maxWidth) {
+        currentLine = currentLine ? `${currentLine} ${word}` : word;
+      } else {
+        if (currentLine) lines.push(currentLine);
+        currentLine = word;
+      }
+    }
+    if (currentLine) lines.push(currentLine);
+
+    return lines;
+  };
+
+  const emptyLine = chalk.gray("│") + " ".repeat(width) + chalk.gray("│");
+  const separator =
+    chalk.gray("│ ") + chalk.gray("─".repeat(width - 2)) + chalk.gray(" │");
+
+  // Build the banner
+  console.log("");
+  console.log(chalk.gray("╭" + border + "╮"));
+  console.log(chalk.gray(emptyLine));
+
+  // App name in light gray
+  console.log(makeLine(chalk.gray(appName)));
+  console.log(emptyLine);
+
+  // Version in amber to match Ctrl+C
+  console.log(makeLine(chalk.yellow(`v${appVersion}`)));
+  console.log(emptyLine);
+
+  // Description (wrapped if needed)
+  if (description) {
+    const wrappedLines = wrapText(description, width - 4);
+    for (const line of wrappedLines) {
+      console.log(makeLine(line));
+    }
+    console.log(emptyLine);
+  }
+
+  console.log(separator);
+  console.log(emptyLine);
+
+  // URLs - no emojis, keys dark gray, values light gray
+  if (webPort && webPort !== port) {
+    // Both web UI and API are configured on different ports
+    console.log(
+      makeLine(
+        `${chalk.gray(" Web UI     :")} ${chalk.gray(`http://localhost:${webPort}`)}`,
+        "left",
+      ),
+    );
+    console.log(
+      makeLine(
+        `${chalk.gray(" API        :")} ${chalk.gray(`http://localhost:${port}/api`)}`,
+        "left",
+      ),
+    );
+  } else if (webPort === port) {
+    // Web UI and API share the same port (production mode)
+    console.log(
+      makeLine(
+        `${chalk.gray(" Web UI     :")} ${chalk.gray(`http://localhost:${port}`)}`,
+        "left",
+      ),
+    );
+    console.log(
+      makeLine(
+        `${chalk.gray(" API        :")} ${chalk.gray(`http://localhost:${port}/api`)}`,
+        "left",
+      ),
+    );
+  } else {
+    // API-only mode
+    console.log(
+      makeLine(
+        `${chalk.gray(" API Server :")} ${chalk.gray(`http://localhost:${port}`)}`,
+        "left",
+      ),
+    );
+    console.log(
+      makeLine(
+        `${chalk.gray(" Endpoints  :")} ${chalk.gray(`http://localhost:${port}/api/*`)}`,
+        "left",
+      ),
+    );
+  }
+  console.log(
+    makeLine(
+      `${chalk.gray(" WebSocket  :")} ${chalk.gray(`ws://localhost:${webSocketPort || port}`)}`,
+      "left",
+    ),
+  );
+
+  console.log(emptyLine);
+  console.log(separator);
+  console.log(emptyLine);
+
+  // Status lines
+  console.log(
+    makeLine(`${chalk.gray(" Ready in")} ${chalk.green(startupTime)}`, "left"),
+  );
+  console.log(
+    makeLine(
+      `${chalk.gray(" Environment:")} ${chalk.gray(environment)}`,
+      "left",
+    ),
+  );
+  console.log(
+    makeLine(
+      `${chalk.gray(" Framework:")} ${chalk.gray(`@superdangerous/app-framework v${version}`)}`,
+      "left",
+    ),
+  );
+
+  console.log(emptyLine);
+  console.log(separator);
+  console.log(emptyLine);
+
+  console.log(
+    makeLine(
+      `${chalk.gray(" Press")} ${chalk.yellow("Ctrl+C")} ${chalk.gray("to stop")}`,
+      "left",
+    ),
+  );
+
+  console.log(chalk.gray(emptyLine));
+  console.log(chalk.gray("╰" + border + "╯"));
+  console.log("");
+}
+
+/**
+ * Display a minimal startup message (for silent mode)
+ */
+export function displayMinimalStartup(appName: string, port: number): void {
+  console.log(
+    chalk.green("✓"),
+    chalk.bold(appName),
+    "started on port",
+    chalk.cyan(port),
+  );
+}